We don't want to be maintaining documentation as well as the source code, which is evolving rapidly at the moment, yet Sphinx seems to require a frustrating amount of setup and configuration. (We just need some basic API docs.) Is there not a single command you can run inside a python project that will just iterate over all of the packages, modules, classes and functions generating documentation as HTML?
The sphinx-apidoc splats stuff into a directory, and after modifying the conf.py to have our packages in the sys.path we can run "make html", but it only lists packages and modules without documenting any classes or functions.
Thanks!
The sphinx-apidoc tool will autogenerate stubs for your modules, which might be what you want.
Instructions
Make sure the autodoc module was enabled during Sphinx configuration.
extensions = ['sphinx.ext.autodoc']
within Sphinx's conf.py should do the trick.
Make sure conf.py adjusts sys.path accordingly (see the comments at lines 16-19 in the file).
sys.path.insert(0, os.path.abspath('/my/source/lives/here'))
Run sphinx-apidoc to generate skeletons.
sphinx-apidoc -o /my/docs/live/here /my/source/lives/here
Rebuild the docs. If all goes well, you shouldn't get the following sort of warning:
mymodule.rst:4: WARNING: autodoc can't import/find module 'mymodule'
Your module RSTs should now be populated.
Related
I am trying out Sphinx for generating documentation for a Python project. Just to make sure I can actually make it work, I have made a test project to try it out on: https://github.com/ThomasA/sphinxtest.
I have run sphinx-quickstart in the root of this repository. In the following questions, I specified 'doc' as the documentation root, named the project 'sphinxtest', entered 'Thomas Arildsen' as author, answered 'y' to the 'autodoc' option, and selected the default setting for everything else.
I expected the 'autodoc' option to cause the generation of a file 'amodule.rst' in the 'doc' folder. However, this does not get generated. I am puzzled by this. I thought this was what the 'autodoc' option was supposed to do and what I have seen examples of others apparently achieve with it. Sphinx completes without any error messages, so it seems to be doing what it thinks it should do. So, what could I be doing wrong?
I am using Sphinx v. 1.5.6 and Python 3.5.3, all installed with Anaconda.
autodoc does not generate the .rst source files.
Instead first use sphinx-apidoc to generate the source files. Then run Sphinx to make your documentation.
An alternative to Percy's answer is autoapi written by Carlos Jenkins. He provides a Sphinx extension that generates the ReST files per documentation generation. You can configure the output ReST by modifying a template file.
https://github.com/carlos-jenkins/autoapi
My python package has a module called settings.py which looks for a settings.ini file, and if one isn't found raises an Exception.
My package works fine but when I try and use Sphinx Autodoc it fails because it can't find a settings file.
What options do I have for getting around this? The ones I can think of are
Put a settings.ini file in one of the Sphinx directories so it can be read.
Somehow mock the internal settings module if possible. The settings module is unimportant so I don't care if there is no documentation for it to the suer
Has anyone run into a similar issue when trying to generate Sphinx documentation on packages that need external files and if so what is your solution?
Pyramid has a command-line script pserve which loads an .ini settings file.
To document this script, we use autoprogram as follows:
.. autoprogram:: pyramid.scripts.pserve:PServeCommand.parser
:prog: pserve
and in your conf.py:
extensions = [
...
'sphinxcontrib.autoprogram',
...
]
It requires the use of argparse in your script.
There are python tools like check-manifest, to verify that all your files under your vcs are included also in your MANIFEST.in. And releasing helpers like zest.releaser recommend you to use them.
I think files in tests or docs directories are never used directly from the python package. Usually services like read the docs or travis-ci are going to access that files, and they get the files from the vcs, not from the package. I have seen also packages including .travis.yml files, what makes even less sense to me.
What is the advantage of including all the files in the python package?
I have a python package and I am able to create sphinx documentation from the python code automatically with
sphinx-apidoc -f -o source --full path_to_package
make html
This works fine, and the html lists all submodules with their documentation.
But in the html I see the following sections/text:
Package name
Submodules
First module
docu...
Second module
docu ...
Each module does have its documentation, but how to place tom documentation text directly below the package name? I want to have the following structure:
Package name
General package documentation...
Submodules
First module
docu...
Second module
docu ...
How to generate a documentation to appear on the top-level of a sphinx-generated documentation, describing the whole package, by ONLY change code in the python package? I do not want to change/add/modify any of the files generated by sphinx.
Is this possible, and how to do that?
First put the documentation as a doc string in the packages __init__.py file.
Then look in the docs folder containing your .rst files.
Edit the .rst for the package - the one with the Module contents at the end.
Then cut the Module Contents section and paste it to be at the top, above subpackages.
Then run make html.
I realise that the op stated only changing python code in the original question, but given his later comment this does seem to be the answer.
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?
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.
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.