Open tcmetzger opened 4 years ago
@tcmetzger I believe that this is covered by selecting y
when prompted with
autodoc: automatically insert docstrings from modules (y/n) [n]:
under sphinx-quickstart
.
See the Sphinx Quickstart section of the tutorial.
The problem is that sphinx-quickstart no longer asks for extensions they can only be added from the command line or edited manually. See Issue: https://github.com/sphinx-doc/sphinx/issues/4148 and PR: https://github.com/sphinx-doc/sphinx/pull/6066
Here is what sphinx-quick start asked me today:
(cq-dev) wink@3900x:~/prgs/python/projects/example-pkg-winksaville/docs (master)
$ sphinx-quickstart
Welcome to the Sphinx 3.2.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: example_pkg_winksaville
> Author name(s): Wink Saville
> Project release []: 0.1.0
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:
Creating file /home/wink/prgs/python/projects/example-pkg-winksaville/docs/source/conf.py.
Creating file /home/wink/prgs/python/projects/example-pkg-winksaville/docs/source/index.rst.
Creating file /home/wink/prgs/python/projects/example-pkg-winksaville/docs/Makefile.
Creating file /home/wink/prgs/python/projects/example-pkg-winksaville/docs/make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file /home/wink/prgs/python/projects/example-pkg-winksaville/docs/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
@sglvladi, It would be great if you could update your tutorial!
As far as I can see, the tutorial does not include instructions on how to enable the autodoc extension for Sphinx in the first place. The file
conf.py
has to includeextensions = ['sphinx.ext.autodoc']
(see https://www.sphinx-doc.org/en/master/usage/quickstart.html#autodoc) to correctly render the autodoc directives. I would suggest adding this information tosphinx-config.rst
. I'd be happy to create a pull request to fix this.