diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 115 |
1 files changed, 63 insertions, 52 deletions
diff --git a/README.rst b/README.rst index 1e027ec8e..54493bb8b 100644 --- a/README.rst +++ b/README.rst @@ -1,3 +1,7 @@ +======== + Sphinx +======== + .. image:: https://img.shields.io/pypi/v/sphinx.svg :target: https://pypi.python.org/pypi/Sphinx .. image:: https://readthedocs.org/projects/sphinx/badge/ @@ -6,40 +10,81 @@ .. image:: https://travis-ci.org/sphinx-doc/sphinx.svg?branch=master :target: https://travis-ci.org/sphinx-doc/sphinx -================= -README for Sphinx -================= +Sphinx is a tool that makes it easy to create intelligent and beautiful +documentation for Python projects (or other documents consisting of multiple +reStructuredText sources), written by Georg Brandl. It was originally created +for the new Python documentation, and has excellent facilities for Python +project documentation, but C/C++ is supported as well, and more languages are +planned. + +Sphinx uses reStructuredText as its markup language, and many of its strengths +come from the power and straightforwardness of reStructuredText and its parsing +and translating suite, the Docutils. + +Among its features are the following: + +* Output formats: HTML (including derivative formats such as HTML Help, Epub + and Qt Help), plain text, manual pages and LaTeX or direct PDF output + using rst2pdf +* Extensive cross-references: semantic markup and automatic links + for functions, classes, glossary terms and similar pieces of information +* Hierarchical structure: easy definition of a document tree, with automatic + links to siblings, parents and children +* Automatic indices: general index as well as a module index +* Code handling: automatic highlighting using the Pygments highlighter +* Flexible HTML output using the Jinja 2 templating engine +* Various extensions are available, e.g. for automatic testing of snippets + and inclusion of appropriately formatted docstrings +* Setuptools integration + +For more information, refer to the `the documentation`__. + +__ http://www.sphinx-doc.org/ + +Installation +============ -This is the Sphinx documentation generator, see http://www.sphinx-doc.org/. +Sphinx is published on `PyPI`__ and can be installed from there:: + pip install -U sphinx -Installing -========== +We also publish beta releases:: -Install from PyPI to use stable version:: + pip install -U --pre sphinx - pip install -U sphinx +If you wish to install `Sphinx` for development purposes, refer to `the +contributors guide`__. -Install from PyPI to use beta version:: +__ https://pypi.python.org/pypi/Sphinx +__ CONTRIBUTING.rst - pip install -U --pre sphinx +Documentation +============= -Install from newest dev version in stable branch:: +Documentation is available from `sphinx-doc.org`__. - pip install git+https://github.com/sphinx-doc/sphinx@stable +__ http://www.sphinx-doc.org/ -Install from newest dev version in master branch:: +Testing +======= - pip install git+https://github.com/sphinx-doc/sphinx +Continuous testing is provided by `Travis`__ (for unit tests and style checks +on Linux), `AppVeyor`__ (for unit tests on Windows), and `CircleCI`__ (for +large processes like TeX compilation). -Install from cloned source:: +For information on running tests locally, refer to `the contributors guide`__. - pip install . +__ https://travis-ci.org/sphinx-doc/sphinx +__ https://ci.appveyor.com/project/sphinxdoc/sphinx +__ https://circleci.com/gh/sphinx-doc/sphinx +__ CONTRIBUTING.rst -Install from cloned source as editable:: +Contributing +============ - pip install -e . +Refer to `the contributors guide`_. +__ CONTRIBUTING.rst Release signatures ================== @@ -48,37 +93,3 @@ Releases are signed with following keys: * `498D6B9E <https://pgp.mit.edu/pks/lookup?op=vindex&search=0x102C2C17498D6B9E>`_ * `5EBA0E07 <https://pgp.mit.edu/pks/lookup?op=vindex&search=0x1425F8CE5EBA0E07>`_ - -Reading the docs -================ - -You can read them online at <http://www.sphinx-doc.org/>. - -Or, after installing:: - - cd doc - make html - -Then, direct your browser to ``_build/html/index.html``. - -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: https://travis-ci.org/sphinx-doc/sphinx - - -Contributing -============ - -See `CONTRIBUTING.rst`__ - -.. __: CONTRIBUTING.rst - |