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
|
{% extends "layout.html" %}
{% set title = _('Overview') %}
{% block body %}
<h1>{{ _('Welcome') }}</h1>
<div class="quotebar">
<p><em>{%trans%}What users say:{%endtrans%}</em></p>
<p>{%trans%}“Cheers for a great tool that actually makes programmers <b>want</b>
to write documentation!“{%endtrans%}</p>
</div>
<p>{%trans%}
Sphinx is a tool that makes it easy to create intelligent and beautiful
documentation, written by Georg Brandl and licensed under the BSD license.{%endtrans%}</p>
<p>{%trans%}It was originally created for <a href="https://docs.python.org/">the
Python documentation</a>, and it has excellent facilities for the
documentation of software projects in a range of languages. Of
course, this site is also created from reStructuredText sources using
Sphinx! The following features should be highlighted:{%endtrans%}
</p>
<ul>
<li>{%trans%}<b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for
printable PDF versions), ePub, Texinfo, manual pages, plain text{%endtrans%}</li>
<li>{%trans%}<b>Extensive cross-references:</b> semantic markup and automatic links
for functions, classes, citations, glossary terms and similar pieces of
information{%endtrans%}</li>
<li>{%trans%}<b>Hierarchical structure:</b> easy definition of a document tree, with
automatic links to siblings, parents and children{%endtrans%}</li>
<li>{%trans%}<b>Automatic indices:</b> general index as well as a language-specific
module indices{%endtrans%}</li>
<li>{%trans%}<b>Code handling:</b> automatic highlighting using the <a
href="https://pygments.org">Pygments</a> highlighter{%endtrans%}</li>
<li>{%trans path=pathto('ext/builtins')%}<b>Extensions:</b> automatic testing of code snippets, inclusion of
docstrings from Python modules (API docs), and
<a href="{{ path }}#builtin-sphinx-extensions">more</a>{%endtrans%}</li>
<li>{%trans path=pathto("usage/extensions/index")%}<b>Contributed extensions:</b> dozens of
extensions <a href="{{ path }}#third-party-extensions">contributed by users</a>;
most of them installable from PyPI{%endtrans%}</li>
</ul>
<p>{%trans%}
Sphinx uses <a href="https://docutils.sourceforge.io/rst.html">reStructuredText</a>
as its markup language, and many of its strengths come from the power and
straightforwardness of reStructuredText and its parsing and translating
suite, the <a href="https://docutils.sourceforge.io/">Docutils</a>.{%endtrans%}
</p>
<h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>
<table class="contentstable">
<tr>
<td>
<p class="biglink"><a class="biglink" href="{{ pathto("usage/quickstart") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
<span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p>
</td><td>
<p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{%trans%}Tutorial{%endtrans%}</a><br/>
<span class="linkdescr">{%trans%}beginners tutorial{%endtrans%}</span></p>
</td>
</tr><tr>
<td>
<p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{%trans%}Contents{%endtrans%}</a><br/>
<span class="linkdescr">{%trans%}for a complete overview{%endtrans%}</span></p>
</td><td>
{%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
<span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
</td>
</tr><tr>
<td>
<p class="biglink"><a class="biglink" href="{{ pathto("changes") }}">{%trans%}Changes{%endtrans%}</a><br/>
<span class="linkdescr">{%trans%}release history{%endtrans%}</span></p>
</td><td>
{%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
<span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
</td><td>
</tr>
</table>
<p>{%trans%}
You can also download PDF/EPUB versions of the Sphinx documentation
from pop up menu on lower right corner.{%endtrans%}
</p>
<h2>{%trans%}Examples{%endtrans%}</h2>
<p>{%trans path=pathto("examples")%}Links to documentation generated with Sphinx can be found on the
<a href="{{ path }}">Projects using Sphinx</a> page.{%endtrans%}
</p>
<p>{%trans%}
For examples of how Sphinx source files look, use the “Show
source” links on all pages of the documentation apart from this
welcome page.{%endtrans%}
</p>
<p>{%trans%}You may also be interested in the very nice
<a href="http://matplotlib.sourceforge.net/sampledoc/">tutorial</a> on how to
create a customized documentation using Sphinx written by the matplotlib
developers.{%endtrans%}</p>
<p>{%trans%}There is a translation team in <a href="https://www.transifex.com/sphinx-doc/sphinx-doc/dashboard/">Transifex</a>
of this documentation, thanks to the Sphinx document translators.{%endtrans%}</p>
<p>{%trans%}A Japanese book about Sphinx has been published by O'Reilly:
<a href="https://www.oreilly.co.jp/books/9784873116488/">Sphinxをはじめよう /
Learning Sphinx</a>.{%endtrans%}</p>
<p>{%trans%}In 2019 the second edition of a German book about Sphinx was published:
<a href="https://literatur.hasecke.com/post/software-dokumentation-mit-sphinx/">Software-Dokumentation mit Sphinx</a>.{%endtrans%}</p>
<!-- <p><img src="{{ pathto("_static/bookcover.png", 1) }}"/></p> -->
<h2>{%trans%}Hosting{%endtrans%}</h2>
<p>{%trans%}Need a place to host your Sphinx docs?
<a href="https://readthedocs.org/">readthedocs.org</a> hosts a lot of Sphinx docs
already, and integrates well with projects' source control. It also features a
powerful built-in search that exceeds the possibilities of Sphinx' JavaScript-based
offline search.{%endtrans%}</p>
<h2>{%trans%}Contributor Guide{%endtrans%}</h2>
<p>{%trans%}If you want to contribute to the project,
this part of the documentation is for you.{%endtrans%}</p>
<ul>
<li>{%trans path=pathto("internals/contributing")%}<a href="{{ path }}">Sphinx Contributors’ Guide</a></li>{%endtrans%}
<li>{%trans path=pathto("internals/authors")%}<a href="{{ path }}">Sphinx Authors</a></li>{%endtrans%}
</ul>
<h2>{%trans%}Code of Conduct{%endtrans%}</h2>
<p>{%trans path=pathto("internals/code-of-conduct")%}Please adhere to our <a href="{{ path }}">Code of Conduct</a>.{%endtrans%}</p>
{% endblock %}
|
