summaryrefslogtreecommitdiffstats
path: root/doc/usage/quickstart.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/usage/quickstart.rst348
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