mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
The Sphinx documentation generator
4a0b28397b
Allow code-blocks at maximal nesting depth of lists/quotes in LaTeX (which by default is 6), by patching fancyvrb's original Verbatim way of checking list depth which resulted in a loss of 1 possible level. Memo 1: latex can have by default a maximum of 4 nested enumerated lists, 4 nested labeled lists, and in total 6 nested lists. This includes quoted blocks as they use the `\list` macro. Memo 2: fancyvrb's rationale for using the \@list... macros (in its \FV@ListNesting) is to set vertical positioning. To set a Verbatim at level N it uses vertical parameters for list level N+1, hence can't work at max level. But in Sphinx, this happens inside a \vbox for framing, hence the vertical positioning set by fancyvrb turns out to be inoperant anyhow. The execution of \@list<level> also sets the \leftmargin, but fancyvrb resets it to zero later (#1=\z@ in \FV@ListNesting). To sum up, fancyvrb's \FV@ListNesting does nothing but has the after effect to raise an error if the code-block is at level equal to max - 1. The effect of this commit is to make inoperant fancyvrb's check of nesting depth, hence now the code-block can appear at maximal depth. This is second commit improving in Sphinx the maximal depth for code-blocks in nested lists or quote blocks. It used to be 4 (with LaTeX's defaults for lists), it is now at 6 (or at the max depth allowed by the document class). |
||
|---|---|---|
| doc | ||
| sphinx | ||
| tests | ||
| utils | ||
| .gitignore | ||
| .travis.yml | ||
| AUTHORS | ||
| babel.cfg | ||
| CHANGES | ||
| CHANGES.old | ||
| EXAMPLES | ||
| LICENSE | ||
| Makefile | ||
| MANIFEST.in | ||
| README.rst | ||
| setup.cfg | ||
| setup.py | ||
| sphinx-apidoc.py | ||
| sphinx-autogen.py | ||
| sphinx-build.py | ||
| sphinx-quickstart.py | ||
| test-reqs.txt | ||
| tox.ini | ||
=================
README for Sphinx
=================
This is the Sphinx documentation generator, see http://sphinx-doc.org/.
Installing
==========
Install from PyPI to use stable version::
pip install -U sphinx
Install from PyPI to use beta version::
pip install -U --pre sphinx
Install from newest dev version in stable branch::
pip install git+https://github.com/sphinx-doc/sphinx@stable
Install from newest dev version in master branch::
pip install git+https://github.com/sphinx-doc/sphinx
Install from cloned source::
pip install .
Install from cloned source as editable::
pip install -e .
Reading the docs
================
After installing::
cd doc
make html
Then, direct your browser to ``_build/html/index.html``.
Or read them online at <http://sphinx-doc.org/>.
Testing
=======
To run the tests with the interpreter available as ``python``, use::
make test
If you want to use a different interpreter, e.g. ``python3``, use::
PYTHON=python3 make test
Continuous testing runs on travis:
.. image:: https://travis-ci.org/sphinx-doc/sphinx.svg?branch=master
:target: https://travis-ci.org/sphinx-doc/sphinx
Contributing
============
#. Check for open issues or open a fresh issue to start a discussion around a
feature idea or a bug.
#. If you feel uncomfortable or uncertain about an issue or your changes, feel
free to email sphinx-dev@googlegroups.com.
#. Fork the repository on GitHub https://github.com/sphinx-doc/sphinx
to start making your changes to the **master** 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. Use ``make test`` to run the test suite.
#. Send a pull request and bug the maintainer until it gets merged and
published. Make sure to add yourself to AUTHORS
<https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS> and the change to
CHANGES <https://github.com/sphinx-doc/sphinx/blob/master/CHANGES>.