diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 13 | ||||
| -rw-r--r-- | doc/_templates/index.html | 4 | ||||
| -rw-r--r-- | doc/_templates/indexsidebar.html | 6 | ||||
| -rw-r--r-- | doc/builders.rst | 23 | ||||
| -rw-r--r-- | doc/conf.py | 4 | ||||
| -rw-r--r-- | doc/config.rst | 11 | ||||
| -rw-r--r-- | doc/contents.rst | 1 | ||||
| -rw-r--r-- | doc/devguide.rst | 214 | ||||
| -rw-r--r-- | doc/domains.rst | 10 | ||||
| -rw-r--r-- | doc/ext/autodoc.rst | 12 | ||||
| -rw-r--r-- | doc/ext/linkcode.rst | 46 | ||||
| -rw-r--r-- | doc/ext/math.rst | 17 | ||||
| -rw-r--r-- | doc/extensions.rst | 1 | ||||
| -rw-r--r-- | doc/intro.rst | 6 | ||||
| -rw-r--r-- | doc/invocation.rst | 11 | ||||
| -rw-r--r-- | doc/markup/misc.rst | 7 |
16 files changed, 349 insertions, 37 deletions
diff --git a/doc/Makefile b/doc/Makefile index 47951316..a46b0227 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -13,7 +13,8 @@ ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) . .PHONY: help clean html dirhtml singlehtml text man pickle json htmlhelp \ - qthelp devhelp epub latex latexpdf changes linkcheck doctest + qthelp devhelp epub latex latexpdf changes linkcheck doctest xml \ + pseudoxml help: @echo "Please use \`make <target>' where <target> is one of" @@ -147,3 +148,13 @@ info: @echo "Running Texinfo files through makeinfo..." make -C _build/texinfo info @echo "makeinfo finished; the Info files are in _build/texinfo." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) _build/xml + @echo + @echo "Build finished. The XML files are in _build/XML." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) _build/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in _build/pseudoxml." diff --git a/doc/_templates/index.html b/doc/_templates/index.html index 34dead7e..8db89ab5 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -62,9 +62,9 @@ <p> You can also download PDF versions of the Sphinx documentation: - a <a href="http://sphinx.pocoo.org/sphinx.pdf">version</a> generated from + a <a href="http://sphinx-doc.org/sphinx.pdf">version</a> generated from the LaTeX Sphinx produces, and - a <a href="http://sphinx.pocoo.org/sphinx-rst2pdf.pdf">version</a> generated + a <a href="http://sphinx-doc.org/sphinx-rst2pdf.pdf">version</a> generated by rst2pdf. </p> diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index feafd904..c479abcb 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -14,14 +14,14 @@ <p>Get Sphinx from the <a href="http://pypi.python.org/pypi/Sphinx">Python Package Index</a>, or install it with:</p> <pre>easy_install -U Sphinx</pre> -<p>Latest <a href="http://sphinx.pocoo.org/latest/">development version docs</a> +<p>Latest <a href="http://sphinx-doc.org/latest/">development version docs</a> are also available.</p> {% endif %} <h3>Questions? Suggestions?</h3> -<p>Join the <a href="http://groups.google.com/group/sphinx-dev">Google group</a>:</p> -<form action="http://groups.google.com/group/sphinx-dev/boxsubscribe" +<p>Join the <a href="http://groups.google.com/group/sphinx-users">Google group</a>:</p> +<form action="http://groups.google.com/group/sphinx-users/boxsubscribe" style="padding-left: 1em"> <input type="text" name="email" value="your@email"/> <input type="submit" name="sub" value="Subscribe" /> diff --git a/doc/builders.rst b/doc/builders.rst index 6600807d..0075ad81 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -272,6 +272,29 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf Its name is ``linkcheck``. +.. module:: sphinx.builders.xml +.. class:: XMLBuilder + + This builder produces Docutils-native XML files. The output can be + transformed with standard XML tools such as XSLT processors into arbitrary + final forms. + + Its name is ``xml``. + + .. versionadded:: 1.2 + +.. class:: PseudoXMLBuilder + + This builder is used for debugging the Sphinx/Docutils "Reader to Transform + to Writer" pipeline. It produces compact pretty-printed "pseudo-XML", files + where nesting is indicated by indentation (no end-tags). External + attributes for all elements are output, and internal attributes for any + leftover "pending" elements are also given. + + Its name is ``pseudoxml``. + + .. versionadded:: 1.2 + Built-in Sphinx extensions that offer more builders are: diff --git a/doc/conf.py b/doc/conf.py index 6b547edd..834b36cf 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -23,14 +23,14 @@ modindex_common_prefix = ['sphinx.'] html_static_path = ['_static'] html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']} html_additional_pages = {'index': 'index.html'} -html_use_opensearch = 'http://sphinx.pocoo.org' +html_use_opensearch = 'http://sphinx-doc.org' htmlhelp_basename = 'Sphinxdoc' epub_theme = 'epub' epub_basename = 'sphinx' epub_author = 'Georg Brandl' -epub_publisher = 'http://sphinx.pocoo.org/' +epub_publisher = 'http://sphinx-doc.org/' epub_scheme = 'url' epub_identifier = epub_publisher epub_pre_files = [('index.html', 'Welcome')] diff --git a/doc/config.rst b/doc/config.rst index 6178d459..0ff6d405 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -383,6 +383,7 @@ documentation on :ref:`intl` for details. * ``ko`` -- Korean * ``lt`` -- Lithuanian * ``lv`` -- Latvian + * ``nb_NO`` -- Norwegian Bokmal * ``ne`` -- Nepali * ``nl`` -- Dutch * ``pl`` -- Polish @@ -1341,6 +1342,16 @@ Options for the linkcheck builder .. versionadded:: 1.2 +Options for the XML builder +--------------------------- + +.. confval:: xml_pretty + + If True, pretty-print the XML. Default is ``True``. + + .. versionadded:: 1.2 + + .. rubric:: Footnotes .. [1] A note on available globbing syntax: you can use the standard shell diff --git a/doc/contents.rst b/doc/contents.rst index 3bbc2835..5e0ae6c1 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -22,6 +22,7 @@ Sphinx documentation contents faq glossary + devguide changes examples diff --git a/doc/devguide.rst b/doc/devguide.rst new file mode 100644 index 00000000..ab4bc740 --- /dev/null +++ b/doc/devguide.rst @@ -0,0 +1,214 @@ +Sphinx Developer's Guide +======================== + +.. topic:: Abstract + + This document describes the development process of Sphinx, a documentation + system used by developers to document systems used by other developers to + develop other systems that may also be documented using Sphinx. + +The Sphinx source code is managed using `Mercurial`_ and is hosted on +`BitBucket`_. + + hg clone https://bitbucket.org/birkenfeld/sphinx + +.. rubric:: Community + +sphinx-users <sphinx-users@googlegroups.com> + Mailing list for user support. + +sphinx-dev <sphinx-dev@googlegroups.com> + Mailing list for development related discussions. + +#pocoo on irc.freenode.net + IRC channel for development questions and user support. + + This channel is shared with other Pocoo projects. Archived logs are + available `here <http://dev.pocoo.org/irclogs/>`_. + +.. _`BitBucket`: http://bitbucket.org +.. _`Mercurial`: http://mercurial.selenic.com/ + + +Bug Reports and Feature Requests +-------------------------------- + +If you have encountered a problem with Sphinx or have an idea for a new +feature, please submit it to the `issue tracker`_ on BitBucket or discuss it +on the sphinx-dev mailing list. + +For bug reports, please include the output produced during the build process +and also the log file Sphinx creates after it encounters an un-handled +exception. The location of this file should be shown towards the end of the +error message. + +Including or providing a link to the source files involved may help us fix the +issue. If possible, try to create a minimal project that produces the error +and post that instead. + +.. _`issue tracker`: http://bitbucket.org/birkenfeld/sphinx/issues + + +Contributing to Sphinx +---------------------- + +The recommended way for new contributors to submit code to Sphinx is to fork +the Mercurial repository on BitBucket and then submit a pull request after +committing the changes. The pull request will then need to be approved by one +of the core developers before it is merged into the main repository. + + +Getting Started +~~~~~~~~~~~~~~~ + +These are the basic steps needed to start developing on Sphinx. + +#. Create an account on BitBucket. + +#. Fork the main Sphinx repository (`birkenfeld/sphinx + <https://bitbucket.org/birkenfeld/sphinx>`_) using the BitBucket interface. + +#. Clone the forked repository to your machine. :: + + hg clone https://bitbucket.org/USERNAME/sphinx-fork + cd sphinx-fork + +#. Checkout the appropriate branch. + + For changes that should be included in the next minor release (namely bug + fixes), use the ``stable`` branch. :: + + hg checkout stable + + For new features or other substantial changes that should wait until the + next major release, use the ``default`` branch. + +#. Setup your Python environment. :: + + virtualenv ~/sphinxenv + . ~/sphinxenv/bin/activate + pip install -e . + +#. Hack, hack, hack. + + For tips on working with the code, see the `Coding Guide`_. + +#. Test, test, test. + + Run the unit tests:: + + pip install nose + make test + + Build the documentation and check the output for different builders:: + + cd docs + make clean html text man info latexpdf + + Run the unit tests under different Python environments using + :program:`tox`:: + + pip install tox + tox -v + + Add a new unit test in the ``tests`` directory if you can. + + For bug fixes, first add a test that fails without your changes and passes + after they are applied. + +#. Commit your changes. :: + + hg commit -m 'Add useful new feature that does this.' + + BitBucket recognizes `certain phrases`__ that can be used to automatically + update the issue tracker. + + For example:: + + hg commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.' + + would close issue #42. + + __ https://confluence.atlassian.com/display/BITBUCKET/Automatically+Resolving+Issues+when+Users+Push+Code + +#. Push changes to your forked repository on BitBucket. :: + + hg push + +#. Submit a pull request from your repository to ``birkenfeld/sphinx`` using + the BitBucket interface. + +#. Wait for a core developer to review your changes. + + +Core Developers +~~~~~~~~~~~~~~~ + +The core developers of Sphinx have write access to the main repository. They +can commit changes, accept/reject pull requests, and manage items on the issue +tracker. + +You do not need to be a core developer or have write access to be involved in +the development of Sphinx. You can submit patches or create pull requests +from forked repositories and have a core developer add the changes for you. + +The following are some general guidelines for core developers: + +* Questionable or extensive changes should be submitted as a pull request + instead of being committed directly to the main repository. The pull + request should be reviewed by another core developer before it is merged. + +* Trivial changes can be committed directly but be sure to keep the repository + in a good working state and that all tests pass before pushing your changes. + +* When committing code written by someone else, please attribute the original + author in the commit message and any relevant :file:`CHANGES` entry. + +* Using Mercurial named branches other than ``default`` and ``stable`` is not + encouraged. + + +Coding Guide +------------ + +* Try to use the same code style as used in the rest of the project. See the + `Pocoo Styleguide`__ for more information. + + __ http://flask.pocoo.org/docs/styleguide/ + +* For non-trivial changes, please update the :file:`CHANGES` file. If your + changes alter existing behavior, please document this. + +* New features should be documented. Include examples and use cases where + appropriate. If possible, include a sample that is displayed in the + generated output. + +* When adding a new configuration variable, be sure to document it and update + :file:`sphinx/quickstart.py`. + +* Use the included :program:`utils/check_sources.py` script to check for + common formatting issues (trailing whitespace, lengthy lines, etc). + +* Add appropriate unit tests. + + +Debugging Tips +~~~~~~~~~~~~~~ + +* Delete the build cache before building documents if you make changes in the + code by running the command ``make clean`` or using the + :option:`sphinx-build -E` option. + +* Use the :option:`sphinx-build -P` option to run Pdb on exceptions. + +* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable + representation of the document structure. + +* Set the configuration variable :confval:`keep_warnings` to True so warnings + will be displayed in the generated output. + +* Set the configuration variable :confval:`nitpicky` to True so that Sphinx + will complain about references without a known target. + +* Set the debugging options in the `Docutils configuration file + <http://docutils.sourceforge.net/docs/user/config.html>`_. diff --git a/doc/domains.rst b/doc/domains.rst index 3d52db3f..bd99a4c5 100644 --- a/doc/domains.rst +++ b/doc/domains.rst @@ -812,7 +812,15 @@ More domains ------------ The sphinx-contrib_ repository contains more domains available as extensions; -currently Ada, Erlang, HTTP, PHP, and Ruby domains. +currently Ada, CoffeeScript_, Erlang_, HTTP_, Jinja_, PHP_, Ruby, and Scala_ +domains. .. _sphinx-contrib: https://bitbucket.org/birkenfeld/sphinx-contrib/ + +.. _CoffeeScript: http://pypi.python.org/pypi/sphinxcontrib-coffee +.. _Erlang: http://pypi.python.org/pypi/sphinxcontrib-erlangdomain +.. _HTTP: http://pypi.python.org/pypi/sphinxcontrib-httpdomain +.. _Jinja: http://pypi.python.org/pypi/sphinxcontrib-jinjadomain +.. _Scala: http://pypi.python.org/pypi/sphinxcontrib-scaladomain +.. _PHP: http://pypi.python.org/pypi/sphinxcontrib-phpdomain diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index ab520f70..7f9a6c61 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -120,6 +120,9 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, .. versionadded:: 1.1 + .. versionchanged:: 1.2 + The option can now take arguments, i.e. the special members to document. + * For classes and exceptions, members inherited from base classes will be left out when documenting all members, unless you give the ``inherited-members`` flag option, in addition to ``members``:: @@ -194,12 +197,13 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, automethod autoattribute - These work exactly like :rst:dir:`autoclass` etc., but do not offer the options - used for automatic member documentation. + These work exactly like :rst:dir:`autoclass` etc., but do not offer the + options used for automatic member documentation. For module data members and class attributes, documentation can either be put - into a special-formatted comment, or in a docstring *after* the definition. - Comments need to be either on a line of their own *before* the definition, or + into a comment with special formatting (using a ``#:`` to start the comment + instead of just ``#``), or in a docstring *after* the definition. Comments + need to be either on a line of their own *before* the definition, or immediately after the assignment *on the same line*. The latter form is restricted to one line only. diff --git a/doc/ext/linkcode.rst b/doc/ext/linkcode.rst new file mode 100644 index 00000000..a69a5b1c --- /dev/null +++ b/doc/ext/linkcode.rst @@ -0,0 +1,46 @@ +:mod:`sphinx.ext.linkcode` -- Add external links to source code +=============================================================== + +.. module:: sphinx.ext.linkcode + :synopsis: Add external links to source code. +.. moduleauthor:: Pauli Virtanen + +.. versionadded:: 1.2 + +This extension looks at your object descriptions (``.. class::``, +``.. function::`` etc.) and adds external links to code hosted +somewhere on the web. The intent is similar to the +``sphinx.ext.viewcode`` extension, but assumes the source code can be +found somewhere on the Internet. + +In your configuration, you need to specify a :confval:`linkcode_resolve` +function that returns an URL based on the object. + +.. confval:: linkcode_resolve + + This is a function ``linkcode_resolve(domain, info)``, + which should return the URL to source code corresponding to + the object in given domain with given information. + + The function should return ``None`` if no link is to be added. + + The argument ``domain`` specifies the language domain the object is + in. ``info`` is a dictionary with the following keys guaranteed to + be present (dependent on the domain): + + - ``py``: ``module`` (name of the module), ``fullname`` (name of the object) + - ``c``: ``names`` (list of names for the object) + - ``cpp``: ``names`` (list of names for the object) + - ``javascript``: ``object`` (name of the object), ``fullname`` (name of the item) + + Example: + + .. code-block:: python + + def linkcode_resolve(domain, info): + if domain != 'py': + return None + if not info['module']: + return None + filename = info['module'].replace('.', '/') + return "http://somesite/sourcerepo/%s.py" % filename diff --git a/doc/ext/math.rst b/doc/ext/math.rst index 3652b55e..91376d15 100644 --- a/doc/ext/math.rst +++ b/doc/ext/math.rst @@ -148,19 +148,12 @@ built: .. confval:: pngmath_dvipng_args Additional arguments to give to dvipng, as a list. The default value is - ``['-gamma 1.5', '-D 110']`` which makes the image a bit darker and larger - then it is by default. + ``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the + image a bit darker and larger then it is by default, and produces PNGs with a + transparent background. - An arguments you might want to add here is e.g. ``'-bg Transparent'``, - which produces PNGs with a transparent background. This is not enabled by - default because some Internet Explorer versions don't like transparent PNGs. - - .. note:: - - When you "add" an argument, you need to reproduce the default arguments if - you want to keep them; that is, like this:: - - pngmath_dvipng_args = ['-gamma 1.5', '-D 110', '-bg Transparent'] + .. versionchanged:: 1.2 + Now includes ``-bg Transparent`` by default. .. confval:: pngmath_use_preview diff --git a/doc/extensions.rst b/doc/extensions.rst index b9397448..07bc7fe4 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -53,6 +53,7 @@ These extensions are built in and can be activated by respective entries in the ext/todo ext/extlinks ext/viewcode + ext/linkcode ext/oldcmarkup diff --git a/doc/intro.rst b/doc/intro.rst index 5d76dd29..4d052c81 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -50,19 +50,15 @@ See the :ref:`pertinent section in the FAQ list <usingwith>`. Prerequisites ------------- -Sphinx needs at least **Python 2.4** or **Python 3.1** to run, as well as the +Sphinx needs at least **Python 2.5** or **Python 3.1** to run, as well as the docutils_ and Jinja2_ libraries. Sphinx should work with docutils version 0.7 or some (not broken) SVN trunk snapshot. If you like to have source code highlighting support, you must also install the Pygments_ library. -If you use **Python 2.4** you also need uuid_. - .. _reStructuredText: http://docutils.sf.net/rst.html .. _docutils: http://docutils.sf.net/ .. _Jinja2: http://jinja.pocoo.org/ .. _Pygments: http://pygments.org/ -.. The given homepage is only a directory listing so I'm using the pypi site. -.. _uuid: http://pypi.python.org/pypi/uuid/ Usage diff --git a/doc/invocation.rst b/doc/invocation.rst index 2c69d32f..da052bdb 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -227,6 +227,17 @@ The :program:`sphinx-apidoc` script has several options: This sets the maximum depth of the table of contents, if one is generated. +.. option:: -l, --follow-links + + This option makes sphinx-apidoc follow symbolic links when recursing the + filesystem to discover packages and modules. You may need it if you want + to generate documentation from a source directory managed by + `collective.recipe.omelette + <http://pypi.python.org/pypi/collective.recipe.omelette/>`_. + By default, symbolic links are skipped. + + .. versionadded:: 1.2 + .. option:: -T, --no-toc This prevents the generation of a table-of-contents file ``modules.rst``. diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index 3a2ffa32..f5eaac9c 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -182,13 +182,6 @@ Including content based on tags The format of the current builder (``html``, ``latex`` or ``text``) is always set as a tag. - .. note:: - - Due to docutils' specifics of parsing of directive content, you cannot put - a section with the same level as the main document heading inside an - ``only`` directive. Such sections will appear to be ignored in the parsed - document. - .. versionadded:: 0.6 |