mjabuz / sphinx

Main repository for the Sphinx documentation builder

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:

Contributing

1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
2. If you feel uncomfortable or uncertain about an issue or your changes, feel free to email [email protected].
3. 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.
4. 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.
5. 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>.