diff options
Diffstat (limited to 'doc/usage/quickstart.rst')
| -rw-r--r-- | doc/usage/quickstart.rst | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst new file mode 100644 index 0000000..0773f60 --- /dev/null +++ b/doc/usage/quickstart.rst @@ -0,0 +1,348 @@ +=============== +Getting Started +=============== + +Sphinx is a *documentation generator* or a tool that translates a set of plain +text source files into various output formats, automatically producing +cross-references, indices, etc. That is, if you have a directory containing a +bunch of :doc:`/usage/restructuredtext/index` or :doc:`/usage/markdown` +documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX), +man pages and much more. + +Sphinx focuses on documentation, in particular handwritten documentation, +however, Sphinx can also be used to generate blogs, homepages and even books. +Much of Sphinx's power comes from the richness of its default plain-text markup +format, :doc:`reStructuredText </usage/restructuredtext/index>`, along with +its :doc:`significant extensibility capabilities </development/index>`. + +The goal of this document is to give you a quick taste of what Sphinx is and +how you might use it. When you're done here, you can check out the +:doc:`installation guide </usage/installation>` followed by the intro to the +default markup format used by Sphinx, :doc:`reStucturedText +</usage/restructuredtext/index>`. + +For a great "introduction" to writing docs in general -- the whys and hows, see +also `Write the docs`__, written by Eric Holscher. + +.. __: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/ + + +Setting up the documentation sources +------------------------------------ + +The root directory of a Sphinx collection of plain-text document sources is +called the :term:`source directory`. This directory also contains the Sphinx +configuration file :file:`conf.py`, where you can configure all aspects of how +Sphinx reads your sources and builds your documentation. [#]_ + +Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a +source directory and creates a default :file:`conf.py` with the most useful +configuration values from a few questions it asks you. To use this, run: + +.. code-block:: console + + $ sphinx-quickstart + + +Defining document structure +--------------------------- + +Let's assume you've run :program:`sphinx-quickstart`. It created a source +directory with :file:`conf.py` and a root document, :file:`index.rst`. The +main function of the :term:`root 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 + + ``toctree`` is a reStructuredText :dfn:`directive`, a very versatile piece + of markup. Directives can have arguments, options and content. + + *Arguments* are given directly after the double colon following the + directive's name. Each directive decides whether it can have arguments, and + how many. + + *Options* are given after the arguments, in form of a "field list". The + ``maxdepth`` is such an option for the ``toctree`` directive. + + *Content* follows the options or arguments after a blank line. Each + directive decides whether to allow content, and what to do with it. + + A common gotcha with directives is that **the first line of the content must + be indented to the same level as the options are**. + +The ``toctree`` directive initially is empty, and looks like so: + +.. code-block:: rst + + .. toctree:: + :maxdepth: 2 + +You add documents listing them in the *content* of the directive: + +.. code-block:: rst + + .. toctree:: + :maxdepth: 2 + + usage/installation + usage/quickstart + ... + +This is exactly how the ``toctree`` for this documentation looks. The +documents to include are given as :term:`document name`\ s, which in short +means that you leave off the file name extension and use forward slashes +(``/``) as directory separators. + +|more| Read more about :ref:`the toctree directive <toctree-directive>`. + +You can now create the files you listed in the ``toctree`` and add content, and +their section titles will be inserted (up to the ``maxdepth`` level) at the +place where the ``toctree`` directive is placed. Also, Sphinx now knows about +the order and hierarchy of your documents. (They may contain ``toctree`` +directives themselves, which means you can create deeply nested hierarchies if +necessary.) + + +Adding content +-------------- + +In Sphinx source files, you can use most features of standard +:term:`reStructuredText`. There are also several features added by Sphinx. +For example, you can add cross-file references in a portable way (which works +for all output types) using the :rst:role:`ref` role. + +For an example, if you are viewing the HTML version, you can look at the source +for this document -- use the "Show Source" link in the sidebar. + +.. todo:: Update the below link when we add new guides on these. + +|more| See :doc:`/usage/restructuredtext/index` for a more in-depth +introduction to reStructuredText, including markup added by Sphinx. + + +Running the build +----------------- + +Now that you have added some files and content, let's make a first build of the +docs. A build is started with the :program:`sphinx-build` program: + +.. code-block:: console + + $ sphinx-build -b html sourcedir builddir + +where *sourcedir* is the :term:`source directory`, and *builddir* is the +directory in which you want to place the built documentation. +The :option:`-b <sphinx-build -b>` option selects a builder; in this example +Sphinx will build HTML files. + +|more| Refer to the :doc:`sphinx-build man page </man/sphinx-build>` for all +options that :program:`sphinx-build` supports. + +However, :program:`sphinx-quickstart` script creates a :file:`Makefile` and a +:file:`make.bat` which make life even easier for you. These can be executed by +running :command:`make` with the name of the builder. For example. + +.. code-block:: console + + $ make html + +This will build HTML docs in the build directory you chose. Execute +:command:`make` without an argument to see which targets are available. + +.. admonition:: How do I generate PDF documents? + + ``make latexpdf`` runs the :mod:`LaTeX builder + <sphinx.builders.latex.LaTeXBuilder>` and readily invokes the pdfTeX + toolchain for you. + + +.. todo:: Move this whole section into a guide on rST or directives + +Documenting objects +------------------- + +One of Sphinx's main objectives is easy documentation of :dfn:`objects` (in a +very general sense) in any :dfn:`domain`. A domain is a collection of object +types that belong together, complete with markup to create and reference +descriptions of these objects. + +The most prominent domain is the Python domain. For example, to document +Python's built-in function ``enumerate()``, you would add this to one of your +source files. + +.. code-block:: rst + + .. py:function:: enumerate(sequence[, start=0]) + + Return an iterator that yields tuples of an index and an item of the + *sequence*. (And so on.) + +This is rendered like this: + +.. py:function:: enumerate(sequence[, start=0]) + + Return an iterator that yields tuples of an index and an item of the + *sequence*. (And so on.) + +The argument of the directive is the :dfn:`signature` of the object you +describe, the content is the documentation for it. Multiple signatures can be +given, each in its own line. + +The Python domain also happens to be the default domain, so you don't need to +prefix the markup with the domain name. + +.. code-block:: rst + + .. function:: enumerate(sequence[, start=0]) + + ... + +does the same job if you keep the default setting for the default domain. + +There are several more directives for documenting other types of Python +objects, for example :rst:dir:`py:class` or :rst:dir:`py:method`. There is +also a cross-referencing :dfn:`role` for each of these object types. This +markup will create a link to the documentation of ``enumerate()``. + +:: + + The :py:func:`enumerate` function can be used for ... + +And here is the proof: A link to :func:`enumerate`. + +Again, the ``py:`` can be left out if the Python domain is the default one. It +doesn't matter which file contains the actual documentation for +``enumerate()``; Sphinx will find it and create a link to it. + +Each domain will have special rules for how the signatures can look like, and +make the formatted output look pretty, or add specific features like links to +parameter types, e.g. in the C/C++ domains. + +|more| See :doc:`/usage/restructuredtext/domains` for all the available domains +and their directives/roles. + + +Basic configuration +------------------- + +Earlier we mentioned that the :file:`conf.py` file controls how Sphinx +processes your documents. In that file, which is executed as a Python source +file, you assign configuration values. For advanced users: since it is +executed by Sphinx, you can do non-trivial tasks in it, like extending +:data:`sys.path` or importing a module to find out the version you are +documenting. + +The config values that you probably want to change are already put into the +:file:`conf.py` by :program:`sphinx-quickstart` and initially commented out +(with standard Python syntax: a ``#`` comments the rest of the line). To +change the default value, remove the hash sign and modify the value. To +customize a config value that is not automatically added by +:program:`sphinx-quickstart`, just add an additional assignment. + +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. + +|more| See :doc:`/usage/configuration` for documentation of all available +config values. + + +.. todo:: Move this entire doc to a different section + +Autodoc +------- + +When documenting Python code, it is common to put a lot of documentation in the +source files, in documentation strings. Sphinx supports the inclusion of +docstrings from your modules with an :dfn:`extension` (an extension is a Python +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:: + + 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 + +You can also document whole classes or even modules automatically, using member +options for the auto directives, like :: + + .. automodule:: io + :members: + +*autodoc* needs to import your modules in order to extract the docstrings. +Therefore, you must add the appropriate path to :py:data:`sys.path` in your +:file:`conf.py`. + +.. warning:: + + :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any + modules have side effects on import, these will be executed by ``autodoc`` + when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their + main routine is protected by a ``if __name__ == '__main__'`` condition. + +|more| See :mod:`sphinx.ext.autodoc` for the complete description of the +features of autodoc. + + +.. todo:: Move this doc to another section + +Intersphinx +----------- + +Many Sphinx documents including the `Python documentation`_ are published on +the Internet. When you want to make links to such documents from your +documentation, you can do it with :mod:`sphinx.ext.intersphinx`. + +.. _Python documentation: https://docs.python.org/3 + +In order to use intersphinx, you need to activate it in :file:`conf.py` by +putting the string ``'sphinx.ext.intersphinx'`` into the :confval:`extensions` +list and set up the :confval:`intersphinx_mapping` config value. + +For example, to link to ``io.open()`` in the Python library manual, you need to +setup your :confval:`intersphinx_mapping` like:: + + intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} + +And now, you can write a cross-reference like ``:py:func:`io.open```. Any +cross-reference that has no matching target in the current documentation set, +will be looked up in the documentation sets configured in +:confval:`intersphinx_mapping` (this needs access to the URL in order to +download the list of valid targets). Intersphinx also works for some other +:term:`domain`\'s roles including ``:ref:``, however it doesn't work for +``:doc:`` as that is non-domain role. + +|more| See :mod:`sphinx.ext.intersphinx` for the complete description of the +features of intersphinx. + + +More topics to be covered +------------------------- + +- :doc:`Other extensions </usage/extensions/index>`: +- Static files +- :doc:`Selecting a theme </usage/theming>` +- :ref:`Templating <templating>` +- Using extensions +- :ref:`Writing extensions <dev-extensions>` + + +.. rubric:: Footnotes + +.. [#] This is the usual layout. However, :file:`conf.py` can also live in + another directory, the :term:`configuration directory`. Refer to the + :doc:`sphinx-build man page </man/sphinx-build>` for more information. + +.. |more| image:: /_static/more.png + :align: middle + :alt: more info |