search

sglvladi / Sphinx-RTD-Tutorial

A tutorial on how to use Sphinx
37 stars 106 forks source link

Enabeling "sphinx.ext.autodoc" is missing from sphinx-config.rst #7

Open tcmetzger opened 4 years ago

tcmetzger commented 4 years ago

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 include extensions = ['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 to sphinx-config.rst. I'd be happy to create a pull request to fix this.

sglvladi commented 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.

winksaville commented 3 years ago

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!