I'm trying to understand how to make Sphinx work.
I'm not Python developer - instead, I want to use reST and Sphinx for general purpose texts.
So, I have Python, DocUtils and Sphinx installed. I have test.rst inside C:\Test\ directory. Then, I launch cmd.exe in this directory and type: sphinx-quickstart. Then, I press Enter multiple times for default presets.
Then I have some new files in this folder, including make.bat. Then, I run: make.bat html. Then, the Sphinx HTML files are created. But when I open index.html - I don't see the contents of my original test.rst.
So, how to make it work?
(Despite the completely identical title, my question is not a duplicate of this in any sense).
You must add test to the toctree directive in your index.rst.
.. toctree::
:maxdepth: 2
test
See the documentation of Directives for additional options and syntax.
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
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.
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.
For a fast preview, I want to build only one file and not all the project. It is possible with sphinx ?
Recently I do something like :
sphinx-build -b html documentation/ doc_html
Sphinx already uses incremental build by writing output files only for new and changed source files. But before that, full build is needed because Sphinx needs to know where the internal links are pointing and where they are referenced from.