From 24b9efb65e276402408d2e76c1899db46c13f636 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Mon, 17 Feb 2020 02:12:27 +0900 Subject: [PATCH] doc: Update usage/quickstart.rst to adjust latest quickstart --- doc/usage/quickstart.rst | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index 8566552e0..b5462a388 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -26,9 +26,6 @@ configuration values from a few questions it asks you. To use this, run: $ sphinx-quickstart -Answer each question asked. Be sure to say "yes" to the ``autodoc`` extension, as -we will use this later. - There is also an automatic "API documentation" generator called :program:`sphinx-apidoc`; see :doc:`/man/sphinx-apidoc` for details. @@ -37,12 +34,11 @@ Defining document structure --------------------------- Let's assume you've run :program:`sphinx-quickstart`. It created a source -directory with :file:`conf.py` and a master document, :file:`index.rst` (if you -accepted the defaults). The main function of the :term:`master document` is to -serve as a welcome page, and to contain the root of the "table of contents -tree" (or *toctree*). This is one of the main things that Sphinx adds to -reStructuredText, a way to connect multiple files to a single hierarchy of -documents. +directory with :file:`conf.py` and a master document, :file:`index.rst`. The +main function of the :term:`master document` is to serve as a welcome page, and +to contain the root of the "table of contents tree" (or *toctree*). This is one +of the main things that Sphinx adds to reStructuredText, a way to connect +multiple files to a single hierarchy of documents. .. sidebar:: reStructuredText directives @@ -233,8 +229,7 @@ customize a config value that is not automatically added by Keep in mind that the file uses Python syntax for strings, numbers, lists and so on. The file is saved in UTF-8 by default, as indicated by the encoding -declaration in the first line. If you use non-ASCII characters in any string -value, you need to use Python Unicode strings (like ``project = u'Exposé'``). +declaration in the first line. |more| See :doc:`/usage/configuration` for documentation of all available config values. @@ -252,10 +247,12 @@ module that provides additional features for Sphinx projects) called *autodoc*. In order to use *autodoc*, you need to activate it in :file:`conf.py` by putting the string ``'sphinx.ext.autodoc'`` into the list assigned to the -:confval:`extensions` config value. Then, you have a few additional directives -at your disposal. +:confval:`extensions` config value:: -For example, to document the function ``io.open()``, reading its signature and + extensions = ['sphinx.ext.autodoc'] + +Then, you have a few additional directives at your disposal. For example, to +document the function ``io.open()``, reading its signature and docstring from the source file, you'd write this:: .. autofunction:: io.open