1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
Metadata-Version: 2.1
Name: Sphinx
Version: 4.5.0
Summary: Python documentation generator
Home-page: https://www.sphinx-doc.org/
Author: Georg Brandl
Author-email: georg@python.org
License: BSD
Download-URL: https://pypi.org/project/Sphinx/
Project-URL: Code, https://github.com/sphinx-doc/sphinx
Project-URL: Issue tracker, https://github.com/sphinx-doc/sphinx/issues
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Framework :: Setuptools Plugin
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Framework :: Sphinx :: Theme
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Classifier: Topic :: Printing
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing
Classifier: Topic :: Text Processing :: General
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: sphinxcontrib-applehelp
Requires-Dist: sphinxcontrib-devhelp
Requires-Dist: sphinxcontrib-jsmath
Requires-Dist: sphinxcontrib-htmlhelp (>=2.0.0)
Requires-Dist: sphinxcontrib-serializinghtml (>=1.1.5)
Requires-Dist: sphinxcontrib-qthelp
Requires-Dist: Jinja2 (>=2.3)
Requires-Dist: Pygments (>=2.0)
Requires-Dist: docutils (<0.18,>=0.14)
Requires-Dist: snowballstemmer (>=1.1)
Requires-Dist: babel (>=1.3)
Requires-Dist: alabaster (<0.8,>=0.7)
Requires-Dist: imagesize
Requires-Dist: requests (>=2.5.0)
Requires-Dist: packaging
Requires-Dist: importlib-metadata (>=4.4) ; python_version < "3.10"
Requires-Dist: colorama (>=0.3.5) ; sys_platform=="win32"
Provides-Extra: docs
Requires-Dist: sphinxcontrib-websupport ; extra == 'docs'
Provides-Extra: lint
Requires-Dist: flake8 (>=3.5.0) ; extra == 'lint'
Requires-Dist: isort ; extra == 'lint'
Requires-Dist: mypy (>=0.931) ; extra == 'lint'
Requires-Dist: docutils-stubs ; extra == 'lint'
Requires-Dist: types-typed-ast ; extra == 'lint'
Requires-Dist: types-requests ; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: html5lib ; extra == 'test'
Requires-Dist: cython ; extra == 'test'
Requires-Dist: typed-ast ; (python_version < "3.8") and extra == 'test'

========
 Sphinx
========

.. image:: https://img.shields.io/pypi/v/sphinx.svg
   :target: https://pypi.org/project/Sphinx/
   :alt: Package on PyPI

.. image:: https://readthedocs.org/projects/sphinx/badge/?version=master
   :target: http://www.sphinx-doc.org/
   :alt: Documentation Status

.. image:: https://ci.appveyor.com/api/projects/status/github/sphinx-doc/sphinx?branch=master&svg=true
   :target: https://ci.appveyor.com/project/sphinxdoc/sphinx
   :alt: Build Status (AppVeyor)

.. image:: https://circleci.com/gh/sphinx-doc/sphinx.svg?style=shield
   :target: https://circleci.com/gh/sphinx-doc/sphinx
   :alt: Build Status (CircleCI)

.. image:: https://codecov.io/gh/sphinx-doc/sphinx/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/sphinx-doc/sphinx
   :alt: Code Coverage Status (Codecov)

.. image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
   :target: https://opensource.org/licenses/BSD-3-Clause
   :alt: BSD 3 Clause

.. image:: https://codetriage.com/sphinx-doc/sphinx/badges/users.svg
   :target: https://codetriage.com/sphinx-doc/sphinx
   :alt: Open Source Helpers badge

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
============

Sphinx is published on `PyPI`__ and can be installed from there::

   pip install -U sphinx

We also publish beta releases::

   pip install -U --pre sphinx

If you wish to install `Sphinx` for development purposes, refer to `the
contributors guide`__.

__ https://pypi.org/project/Sphinx/
__ http://www.sphinx-doc.org/en/master/internals/contributing.html

Documentation
=============

Documentation is available from `sphinx-doc.org`__.

__ http://www.sphinx-doc.org/

Get in touch
============

- Report bugs, suggest features or view the source code `on GitHub`_.
- For less well defined questions or ideas, use the `mailing list`_.

.. _on GitHub: https://github.com/sphinx-doc/sphinx
.. _mailing list: https://groups.google.com/forum/#!forum/sphinx-users

Please adhere to our `code of conduct`__.

__ http://www.sphinx-doc.org/en/master/code_of_conduct.html

Testing
=======

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).

For information on running tests locally, refer to `the contributors guide`__.

__ https://travis-ci.org/sphinx-doc/sphinx
__ https://ci.appveyor.com/project/sphinxdoc/sphinx
__ https://circleci.com/gh/sphinx-doc/sphinx
__ http://www.sphinx-doc.org/en/master/internals/contributing.html

Contributing
============

Refer to `the contributors guide`__.

__ http://www.sphinx-doc.org/en/master/internals/contributing.html

Release signatures
==================

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>`_