mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
The Sphinx documentation generator
aa31bae17a
This cleans up comments from sphinxmanual.cls. Memo: the logic behind the earlier sphinxmanual.cls is obscure, besides the fact that it didn't work correctly if conf.py used openany option. The parent commit corrected the implementation, but not the logic. Were it not for the log message about added blank page, there would be no need to patch \tableofcontents, because by default it will use \chapter* which does the right thing. Similarly after the end of abstract, a \chapter or \part (or \tableofcontents, once abstract is properly handled by LaTeX writer (*)), currently one seems to be contrived to use raw directive and the abstract is then after \tableofcontents) will do the right thing in case of openany. Also the \maketitle wrongly ended with \cleardoublepage, which was corrected in parent commit, but better would be that it does nothing. Indeed it is not logical for \maketitle, abstract or \tableofcontents to worry about what comes next. Anything which comes next should be a \part or \chapter which will do the right thing. (*) currently one seems to be contrived to use raw directive and the abstract is then after \tableofcontents) will do the right thing in case of openany. |
||
|---|---|---|
| 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>.