Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
tcmetzger opened this issue Jun 6, 2020 · 2 comments
Open

Comments

@tcmetzger
Copy link

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
Copy link
Owner

sglvladi commented Jul 8, 2020

@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
Copy link

winksaville commented Oct 2, 2020

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: sphinx-doc/sphinx#4148 and PR: sphinx-doc/sphinx#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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants