Georg Brandl committed d3d47e6

A bit more tutorial.

Comments (0)

Files changed (2)


         .. autoclass:: Noodle
            :members: eat, slurp
+   * If you want to make the ``members`` option the default, see
+     :confval:`autodoc_default_flags`.
    * Members without docstrings will be left out, unless you give the
      ``undoc-members`` flag option::
 In Sphinx source files, you can use most features of standard 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 :role:`ref` role.  Here is a small example of how a source file could look
+the :role:`ref` role.
-   XXX
+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.
 |more| See :ref:`rst-primer` for a more in-depth introduction to
 reStructuredText and :ref:`sphinxmarkup` for a full list of markup added by
 Running the build
-Now that you have added some files and content, let's build the docs.  A build
-is started with the :program:`sphinx-build` script, called like this::
+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, called like
    $ sphinx-build -b html sourcedir builddir
 :confval:`extensions` config value.  Then, you have a few additional directives
 at your disposal.
+For example, to document the function ````, reading its
+signature and docstring from the source file, you'd write this::
+   .. autofunction::
+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
 |more| See :mod:`sphinx.ext.autodoc` for the complete description of the
 features of autodoc.
-Topics to be covered
+More topics to be covered
 - Other extensions (math, intersphinx, viewcode, doctest)
 - Static files