CODEWITHSUNDEEP
pythondocumentationpython-sphinx
Daniel Lee
Daniel Lee

Reputation: 2070

Sphinx uses old module code

I use Sphinx to document my code, which is a collection of Python modules. The autogenerated documentation that's made by scrubbing my source code is fine, but when I click on the "code" link that links directly to the HTML pages containing my package's sources that Sphinx generates, an older version of my code is shown.

I've tried deleting my Sphinx generated documentation, uninstalling the package from my own site-packages folder, and deleting everything in my build folder. I can find absolutely no files that match Sphinx's output - it's old, and I'm not sure where it's coming from. Does anybody know how to get Sphinx to put my new code in the documentation?

As I said, the autodocumentation works fine, so it's obviously parsing my code on some level. So why is the pure text different from the autodocumentation?

Upvotes: 11

Views: 3605

Answers (2)

Cecil Curry
Cecil Curry

Reputation: 10226

Pass the poorly documented -a option to sphinx-build.

Doing so effectively disables all Sphinx caching by forcing Sphinx to rebuild all output documentation files (e.g., HTML in the docs/build/ subdirectory), regardless of whether the underlying source input files have been directly modified or not. This is my preferred mode of operation when locally authoring Sphinx documentation, because I frankly do not trust Sphinx to safely cache what I expect it to. It never does.

For safety, I also:

  • Prefer directly calling sphinx-build to indirectly invoking Sphinx through makefiles (e.g., make html).
  • Pass -W, converting non-fatal warnings into fatal errors.
  • Pass --keep-going, collecting all warnings before failing (rather than immediately failing on the first warning).
  • Pass -n, enabling "nit-picky mode" generating one warning for each broken reference (e.g., interdocument or intrasection link).
  • Pass -j auto, parallelizing the build process across all available CPU cores.

I have trust issues. I'm still shell-shocked from configuring Sphinx for ReadTheDocs three all-nighters ago. Now, I always locally run Sphinx via this command (wrapped in a Bash shell script or alias for convenience):

$ sphinx-build -M html doc/source/ doc/build/ -W -a -j auto -n --keep-going

That's just how we roll, Sphinx. It's Bash or bust.

Upvotes: 5

mzjn
mzjn

Reputation: 50947

Sphinx caches (pickles) parsed source files. The cache is usually located in a directory called .doctrees under the build directory. To ensure that your source files are reparsed, delete this directory.

See http://www.sphinx-doc.org/en/stable/man/sphinx-build.html#cmdoption-sphinx-build-d.

Upvotes: 6

Related Questions