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

Add documentation to make contribution easier.

Browse Source
This commit is contained in:
Takayuki Shimizukawa
2014-08-31 00:02:01 +09:00
parent 9acf2527ce
commit 0cfb00db79
7 changed files with 175 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
AUTHORS
View File

@@ -3,6 +3,21 @@ Sphinx is written and maintained by Georg Brandl <georg@python.org>.
Substantial parts of the templates were written by Armin Ronacher
<armin.ronacher@active-4.com>.
Other co-maintainers, listed alphabetically, are:
* Daniel Neuhäuser <@DasIch>
* Dag Odenhall <@dag>
* Ervin Hegedüs <@airween>
* jacobmason <@jacobmason>
* Jon Waltman <@jonwaltman>
* Kevin Hunter <@hunteke>
* La Min Ko <@lminko>
* Nikolaj van Omme <@nvanomme>
* Rob Ruana <@RelentlessIdiot>
* Robert Lehmann <@lehmannro>
* Roland Meister <@rolmei>
* Takayuki Shimizukawa <@shimizukawa>
Other contributors, listed alphabetically, are:
* Andi Albrecht -- agogo theme

198
CHANGES
View File

@@ -4,186 +4,197 @@ Release 1.3 (in development)
Incompatible changes
--------------------
* Dropped support for Python 2.5, 3.1 and 3.2.
* Dropped support for docutils versions up to 0.9.
* Removed the ``sphinx.ext.oldcmarkup`` extension.
* Dropped support for Python 2.5, 3.1 and 3.2. [shimizukawa]
* Dropped support for docutils versions up to 0.9. [shimizukawa]
* Removed the ``sphinx.ext.oldcmarkup`` extension. [birkenfeld]
* The deprecated config values ``exclude_trees``, ``exclude_dirnames`` and
``unused_docs`` have been removed.
``unused_docs`` have been removed. [birkenfeld]
* A new node, ``sphinx.addnodes.literal_strong``, has been added, for text that
should appear literally (i.e. no smart quotes) in strong font. Custom writers
will have to be adapted to handle this node.
will have to be adapted to handle this node. [birkenfeld]
* PR#269, #1476: replace `<tt>` tag by `<code>`. User customized stylesheets
should be updated If the css contain some styles for `<tt>` tag.
Thanks to Takeshi Komiya.
should be updated If the css contain some styles for `<tt>` tag. [tk0miya]
* #1543: :confval:`templates_path` is automatically added to
:confval:`exclude_patterns` to avoid reading autosummary rst templates in the
templates directory.
templates directory. [shimizukawa]
Features added
--------------
* Add support for Python 3.4.
* Add support for docutils 0.12
* Add support for Python 3.4. [shimizukawa]
* Add support for docutils 0.12. [shimizukawa]
* Added ``sphinx.ext.napoleon`` extension for NumPy and Google style docstring
support.
support. [RelentlessIdiot]
* PR#214: Added stemming support for 14 languages, so that the built-in document
search can now handle these. Thanks to Shibukawa Yoshiki.
search can now handle these. [shibu]
* PR#202: Allow "." and "~" prefixed references in ``:param:`` doc fields
for Python.
for Python. [birkenfeld]
* PR#184: Add :confval:`autodoc_mock_imports`, allowing to mock imports of
external modules that need not be present when autodocumenting.
external modules that need not be present when autodocumenting. [birkenfeld]
* #925: Allow list-typed config values to be provided on the command line,
like ``-D key=val1,val2``.
like ``-D key=val1,val2``. [birkenfeld]
* #668: Allow line numbering of ``code-block`` and ``literalinclude`` directives
to start at an arbitrary line number, with a new ``lineno-start`` option.
[birkenfeld]
* PR#172, PR#266: The :rst:dir:`code-block` and :rst:dir:`literalinclude`
directives now can have a ``caption`` option that shows a filename before the
code in the output. Thanks to Nasimul Haque, Takeshi Komiya.
* Prompt for the document language in sphinx-quickstart.
code in the output. [nsmgr8, tk0miya]
* Prompt for the document language in sphinx-quickstart. [birkenfeld]
* PR#217: Added config values to suppress UUID and location information in
generated gettext catalogs.
generated gettext catalogs. [kenhys]
* PR#236, #1456: apidoc: Add a -M option to put module documentation before
submodule documentation. Thanks to Wes Turner and Luc Saffre.
submodule documentation. [westurner, Luc Saffre]
* #1434: Provide non-minified JS files for jquery.js and underscore.js to
clarify the source of the minified files.
* PR#252, #1291: Windows color console support. Thanks to meu31.
clarify the source of the minified files. [shimizukawa]
* PR#252, #1291: Windows color console support. [meu31]
* PR#255: When generating latex references, also insert latex target/anchor
for the ids defined on the node. Thanks to Olivier Heurtier.
* PR#229: Allow registration of other translators. Thanks to Russell Sim.
for the ids defined on the node. [olivier-heurtier]
* PR#229: Allow registration of other translators. [russell, shimizukawa]
* Add app.set_translator() API to register or override a Docutils translator
class like :confval:`html_translator_class`.
* PR#267, #1134: add 'diff' parameter to literalinclude. Thanks to Richard Wall
and WAKAYAMA shirou.
* PR#272: Added 'bizstyle' theme. Thanks to Shoji KUMAGAI.
class like :confval:`html_translator_class`. [shimizukawa]
* PR#267, #1134: add 'diff' parameter to literalinclude. [wallr, r_rudi]
* PR#272: Added 'bizstyle' theme. [shkumagai]
* Automatically compile ``*.mo`` files from ``*.po`` files when
:confval:`gettext_auto_build` is True (default) and ``*.po`` is newer than
``*.mo`` file.
``*.mo`` file. [shimizukawa]
* #623: :mod:`~sphinx.ext.viewcode` supports imported function/class aliases.
[shimizukawa]
* PR#275: :mod:`~sphinx.ext.intersphinx` supports multiple target for the
inventory. Thanks to Brigitta Sipocz.
inventory. [bsipocz]
Bugs fixed
----------
* #1174: Fix smart quotes being applied inside roles like :rst:role:`program` or
:rst:role:`makevar`.
:rst:role:`makevar`. [birkenfeld]
* #1335: Fix autosummary template overloading with exclamation prefix like
``{% extends "!autosummary/class.rst" %}`` cause infinite recursive function
call. This was caused by PR#181.
call. This was caused by PR#181. [shimizukawa]
* #1337: Fix autodoc with ``autoclass_content="both"`` uses useless
``object.__init__`` docstring when class does not have ``__init__``.
This was caused by a change for #1138.
This was caused by a change for #1138. [shimizukawa]
* #1340: Can't search alphabetical words on the HTML quick search generated
with language='ja'.
with language='ja'. [shimizukawa]
* #1319: Do not crash if the :confval:`html_logo` file does not exist.
[birkenfeld]
* #603: Do not use the HTML-ized title for building the search index (that
resulted in "literal" being found on every page with a literal in the
title).
title). [birkenfeld]
* #751: Allow production lists longer than a page in LaTeX by using longtable.
* #764: Always look for stopwords lowercased in JS search.
[birkenfeld]
* #764: Always look for stopwords lowercased in JS search. [birkenfeld]
* #814: autodoc: Guard against strange type objects that don't have
``__bases__``.
* #932: autodoc: Do not crash if ``__doc__`` is not a string.
``__bases__``. [birkenfeld]
* #932: autodoc: Do not crash if ``__doc__`` is not a string. [birkenfeld]
* #933: Do not crash if an :rst:role:`option` value is malformed (contains
spaces but no option name).
spaces but no option name). [birkenfeld]
* #908: On Python 3, handle error messages from LaTeX correctly in the pngmath
extension.
extension. [birkenfeld]
* #943: In autosummary, recognize "first sentences" to pull from the docstring
if they contain uppercase letters.
if they contain uppercase letters. [birkenfeld]
* #923: Take the entire LaTeX document into account when caching
pngmath-generated images. This rebuilds them correctly when
:confval:`pngmath_latex_preamble` changes.
:confval:`pngmath_latex_preamble` changes. [birkenfeld]
* #901: Emit a warning when using docutils' new "math" markup without a Sphinx
math extension active.
math extension active. [birkenfeld]
* #845: In code blocks, when the selected lexer fails, display line numbers
nevertheless if configured.
* #929: Support parsed-literal blocks in LaTeX output correctly.
* #949: Update the tabulary.sty packed with Sphinx.
nevertheless if configured. [birkenfeld]
* #929: Support parsed-literal blocks in LaTeX output correctly. [birkenfeld]
* #949: Update the tabulary.sty packed with Sphinx. [birkenfeld]
* #1050: Add anonymous labels into ``objects.inv`` to be referenced via
:mod:`~sphinx.ext.intersphinx`.
:mod:`~sphinx.ext.intersphinx`. [birkenfeld]
* #1095: Fix print-media stylesheet being included always in the "scrolls"
theme.
theme. [birkenfeld]
* #1085: Fix current classname not getting set if class description has
``:noindex:`` set.
``:noindex:`` set. [birkenfeld]
* #1181: Report option errors in autodoc directives more gracefully.
[birkenfeld]
* #1155: Fix autodocumenting C-defined methods as attributes in Python 3.
[birkenfeld]
* #1233: Allow finding both Python classes and exceptions with the "class" and
"exc" roles in intersphinx.
"exc" roles in intersphinx. [birkenfeld]
* #1198: Allow "image" for the "figwidth" option of the :rst:dir:`figure`
directive as documented by docutils.
directive as documented by docutils. [birkenfeld]
* #1152: Fix pycode parsing errors of Python 3 code by including two grammar
versions for Python 2 and 3, and loading the appropriate version for the
running Python version.
running Python version. [birkenfeld]
* #1017: Be helpful and tell the user when the argument to :rst:dir:`option`
does not match the required format.
does not match the required format. [birkenfeld]
* #1345: Fix two bugs with :confval:`nitpick_ignore`; now you don't have to
remove the store environment for changes to have effect.
remove the store environment for changes to have effect. [birkenfeld]
* #1072: In the JS search, fix issues searching for upper-cased words by
lowercasing words before stemming.
lowercasing words before stemming. [birkenfeld]
* #1299: Make behavior of the :rst:dir:`math` directive more consistent and
avoid producing empty environments in LaTeX output.
avoid producing empty environments in LaTeX output. [birkenfeld]
* #1308: Strip HTML tags from the content of "raw" nodes before feeding it
to the search indexer.
* #1249: Fix duplicate LaTeX page numbering for manual documents.
to the search indexer. [birkenfeld]
* #1249: Fix duplicate LaTeX page numbering for manual documents. [birkenfeld]
* #1292: In the linkchecker, retry HEAD requests when denied by HTTP 405.
Also make the redirect code apparent and tweak the output a bit to be
more obvious.
more obvious. [birkenfeld]
* #1285: Avoid name clashes between C domain objects and section titles.
[birkenfeld]
* #848: Always take the newest code in incremental rebuilds with the
:mod:`sphinx.ext.viewcode` extension.
* #979, #1266: Fix exclude handling in ``sphinx-apidoc``.
:mod:`sphinx.ext.viewcode` extension. [birkenfeld]
* #979, #1266: Fix exclude handling in ``sphinx-apidoc``. [birkenfeld]
* #1302: Fix regression in :mod:`sphinx.ext.inheritance_diagram` when
documenting classes that can't be pickled.
documenting classes that can't be pickled. [birkenfeld]
* #1316: Remove hard-coded ``font-face`` resources from epub theme.
* #1329: Fix traceback with empty translation msgstr in .po files.
[birkenfeld]
* #1329: Fix traceback with empty translation msgstr in .po files. [birkenfeld]
* #1300: Fix references not working in translated documents in some instances.
[birkenfeld]
* #1283: Fix a bug in the detection of changed files that would try to access
doctrees of deleted documents.
doctrees of deleted documents. [birkenfeld]
* #1330: Fix :confval:`exclude_patterns` behavior with subdirectories in the
:confval:`html_static_path`.
:confval:`html_static_path`. [birkenfeld]
* #1323: Fix emitting empty ``<ul>`` tags in the HTML writer, which is not
valid HTML.
valid HTML. [birkenfeld]
* #1147: Don't emit a sidebar search box in the "singlehtml" builder.
[birkenfeld]
* PR#211: When checking for existence of the :confval:`html_logo` file, check
the full relative path and not the basename.
the full relative path and not the basename. [ViktorHaag]
* #1357: Option names documented by :rst:dir:`option` are now again allowed to
not start with a dash or slash, and referencing them will work correctly.
[birkenfeld]
* #1358: Fix handling of image paths outside of the source directory when using
the "wildcard" style reference.
the "wildcard" style reference. [shimizukawa]
* #1374: Fix for autosummary generating overly-long summaries if first line
doesn't end with a period.
doesn't end with a period. [birkenfeld]
* #1391: Actually prevent using "pngmath" and "mathjax" extensions at the same
time in sphinx-quickstart.
time in sphinx-quickstart. [birkenfeld]
* #1386: Fix bug preventing more than one theme being added by the entry point
mechanism.
* #1370: Ignore "toctree" nodes in text writer, instead of raising.
mechanism. [birkenfeld]
* #1370: Ignore "toctree" nodes in text writer, instead of raising. [birkenfeld]
* #1364: Fix 'make gettext' fails when the '.. todolist::' directive is present.
[shimizukawa]
* #1367: Fix a change of PR#96 that break sphinx.util.docfields.Field.make_field
interface/behavior for `item` argument usage.
interface/behavior for `item` argument usage. [shimizukawa]
* #1363: Fix i18n: missing python domain's cross-references with currentmodule
directive or currentclass directive.
directive or currentclass directive. [shimizukawa]
* #1419: Generated i18n sphinx.js files are missing message catalog entries
from '.js_t' and '.html'. The issue was introduced in Sphinx 1.1.
[shimizukawa]
* #636: Keep straight single quotes in literal blocks in the LaTeX build.
[birkenfeld]
* PR#235: comment db schema of websupport lacked a length of the node_id field.
Thanks to solos.
[solos]
* #1466,PR#241: Fix failure of the cpp domain parser to parse C+11
"variadic templates" declarations. Thanks to Victor Zverovich.
"variadic templates" declarations. [vitaut]
* #1459,PR#244: Fix default mathjax js path point to `http://` that cause
mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k.
mixed-content error on HTTPS server. [sbrandtb, robo9k].
* PR#157: autodoc remove spurious signatures from @property decorated
attributes. Thanks to David Ham.
attributes. [David_Ham]
* PR#159: Add coverage targets to quickstart generated Makefile and make.bat.
Thanks to Matthias Troffaes.
[mcmtroffaes]
* #1251: When specifying toctree :numbered: option and :tocdepth: metadata,
sub section number that is larger depth than `:tocdepth:` is shrinked.
* PR#260: Encode underscore in citation labels for latex export. Thanks to
Lennart Fricke.
[shimizukawa]
* PR#260: Encode underscore in citation labels for latex export. [lennart0901]
* PR#264: Fix could not resolve xref for figure node with :name: option.
Thanks to Takeshi Komiya.
* PR#265: Fix could not capture caption of graphviz node by xref. Thanks to
Takeshi Komiya.
* PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke Andersen.
[tk0miya]
* PR#265: Fix could not capture caption of graphviz node by xref. [tk0miya]
* PR#263, #1013, #1103: Rewrite of C++ domain. [jakobla]
* Hyperlinks to all found nested names and template arguments (#1103).
* Support for function types everywhere, e.g., in
@@ -201,28 +212,31 @@ Bugs fixed
potentially index by namespaces/classes as well.
* PR#258, #939: Add dedent option for :rst:dir:`code-block` and
:rst:dir:`literal-include`. Thanks to Zafar Siddiqui.
:rst:dir:`literal-include`. [zsiddiqui2]
* PR#268: Fix numbering section does not work at singlehtml mode. It still
ad-hoc fix because there is a issue that section IDs are conflicted.
Thanks to Takeshi Komiya.
* PR#273, #1536: Fix RuntimeError with numbered circular toctree. Thanks to
Takeshi Komiya.
[tk0miya]
* PR#273, #1536: Fix RuntimeError with numbered circular toctree. [tk0miya]
* PR#274: Set its URL as a default title value if URL appears in toctree.
Thanks to Takeshi Komiya.
[tk0miya]
* PR#276, #1381: :rst:role:`rfc` and :rst:role:`pep` roles support custom link
text. Thanks to Takeshi Komiya.
text. [tk0miya]
* PR#277, #1513: highlights for function pointers in argument list of
:rst:dir:`c:function`. Thanks to Takeshi Komiya.
:rst:dir:`c:function`. [tk0miya]
* PR#278: Fix section entries were shown twice if toctree has been put under
only directive. Thanks to Takeshi Komiya.
only directive. [tk0miya]
* #1547: pgen2 tokenizer doesn't recognize `...` literal (Ellipsis for py3).
[shimizukawa]
Documentation
-------------
* Add clarification about the syntax of tags. (:file:`doc/markup/misc.rst`)
[davidjb]
* #1325: Added a "Intersphinx" tutorial section. (:file:`doc/tutorial.rst`)
[birkenfeld]
* Extended the :ref:`documentation about building extensions <dev-extensions>`.
[birkenfeld]
Release 1.2.3 (in development)

18
README.rst
View File

@@ -39,4 +39,20 @@ If you want to use a different interpreter, e.g. ``python3``, use::
Contributing
============
Send wishes, comments, patches, etc. to sphinx-dev@googlegroups.com.
#. Check for open issues or open a fresh issue to start a discussion around a
feature idea or a bug. There are `Non Assigned`_ issues.
#. If you feel uncomfortable or uncertain about an issue or your changes, feel
free to email sphinx-dev@googlegroups.com.
#. Fork `the repository`_ on Bitbucket to start making your changes to the
**default** branch for next major version, or **stable** branch for next
minor version.
#. Write a test which shows that the bug was fixed or that the feature works
as expected.
#. Send a pull request and bug the maintainer until it gets merged and
published. :) Make sure to add yourself to AUTHORS_ and the change to
CHANGES_.
.. _`the repository`: https://bitbucket.org/birkenfeld/sphinx
.. _AUTHORS: https://bitbucket.org/birkenfeld/sphinx/src/tip/AUTHORS
.. _CHANGES: https://bitbucket.org/birkenfeld/sphinx/src/tip/CHANGES
.. _Non Assigned: https://bitbucket.org/birkenfeld/sphinx/issues?status=new&status=open&responsible=

10
doc/_templates/index.html vendored
View File

@@ -97,4 +97,14 @@
powerful built-in search that exceeds the possibilities of Sphinx' JavaScript-based
offline search.{%endtrans%}</p>
<h2>{%trans%}Contributor Guide{%endtrans%}</h2>
<p>{%trans%}If you want to contribute to the project,
this part of the documentation is for you.{%endtrans%}</p>
<ul>
<li>{%trans path=pathto("devguide")%}<a href="{{ path }}">Sphinx Developer’s Guide</a></li>{%endtrans%}
<li>{%trans path=pathto("authors")%}<a href="{{ path }}">Sphinx Authors</a></li>{%endtrans%}
</ul>
{% endblock %}

9
doc/authors.rst Normal file
View File

@@ -0,0 +1,9 @@
:tocdepth: 2
.. _authors:
Sphinx authors
==============
.. include:: ../AUTHORS

1
doc/contents.rst
View File

@@ -26,6 +26,7 @@ Sphinx documentation contents
devguide
changes
examples
authors
Indices and tables

17
doc/devguide.rst
View File

@@ -54,6 +54,23 @@ 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.
#. Check for open issues or open a fresh issue to start a discussion around a
feature idea or a bug. There are `Non Assigned`_ issues.
#. If you feel uncomfortable or uncertain about an issue or your changes, feel
free to email sphinx-dev@googlegroups.com.
#. Fork `the repository`_ on Bitbucket to start making your changes to the
**default** branch for next major version, or **stable** branch for next
minor version.
#. Write a test which shows that the bug was fixed or that the feature works
as expected.
#. Send a pull request and bug the maintainer until it gets merged and
published. :) Make sure to add yourself to AUTHORS_ and the change to
CHANGES_.
.. _`the repository`: https://bitbucket.org/birkenfeld/sphinx
.. _AUTHORS: https://bitbucket.org/birkenfeld/sphinx/src/tip/AUTHORS
.. _CHANGES: https://bitbucket.org/birkenfeld/sphinx/src/tip/CHANGES
.. _Non Assigned: https://bitbucket.org/birkenfeld/sphinx/issues?status=new&status=open&responsible=
Getting Started
~~~~~~~~~~~~~~~