IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

doc: Update usage/quickstart.rst to adjust latest quickstart

Browse Source
This commit is contained in:
Takeshi KOMIYA 2020-02-17 02:12:27 +09:00
parent 59c973c8c2
commit 24b9efb65e
1 changed files with 11 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/usage/quickstart.rst
View File

@ -26,9 +26,6 @@ configuration values from a few questions it asks you. To use this, run:
$ sphinx-quickstart $ 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 There is also an automatic "API documentation" generator called
:program:`sphinx-apidoc`; see :doc:`/man/sphinx-apidoc` for details. :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 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 directory with :file:`conf.py` and a master document, :file:`index.rst`. The
accepted the defaults). The main function of the :term:`master document` is to main function of the :term:`master document` is to serve as a welcome page, and
serve as a welcome page, and to contain the root of the "table of contents to contain the root of the "table of contents tree" (or *toctree*). This is one
tree" (or *toctree*). This is one of the main things that Sphinx adds to of the main things that Sphinx adds to reStructuredText, a way to connect
reStructuredText, a way to connect multiple files to a single hierarchy of multiple files to a single hierarchy of documents.
documents.
.. sidebar:: reStructuredText directives .. 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 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 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 declaration in the first line.
value, you need to use Python Unicode strings (like ``project = u'Exposé'``).
|more| See :doc:`/usage/configuration` for documentation of all available |more| See :doc:`/usage/configuration` for documentation of all available
config values. 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 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 putting the string ``'sphinx.ext.autodoc'`` into the list assigned to the
:confval:`extensions` config value. Then, you have a few additional directives :confval:`extensions` config value::
at your disposal.
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:: docstring from the source file, you'd write this::
.. autofunction:: io.open .. autofunction:: io.open