IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Refresh the Sphinx13 theme (#10652)

Browse Source
This commit is contained in:
Adam Turner
2022-07-10 22:48:15 +01:00
committed by GitHub
parent 3db1844d9a
commit 9112cfeb8d
17 changed files with 225 additions and 438 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/_static/pocoo.png vendored
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.5 KiB

6
doc/_templates/contents.html vendored Normal file
View File

@@ -0,0 +1,6 @@
{% extends "layout.html" %}
{% set title = _('Sphinx documentation contents') %}
{% block body %}
<h1>{{ _('Sphinx documentation contents') }}</h1>
{{ toctree(includehidden=True, collapse=False, maxdepth=3) }}
{% endblock %}

129
doc/_templates/index.html vendored
View File

@@ -1,129 +0,0 @@
{% 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%}&#8220;Cheers for a great tool that actually makes programmers <b>want</b>
to write documentation!&#8220;{%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 &#8220;Show
source&#8221; 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 %}

23
doc/_templates/indexsidebar.html vendored
View File

@@ -1,23 +0,0 @@
<p class="logo">A <a href="https://www.pocoo.org/">
<img src="{{ pathto("_static/pocoo.png", 1) }}" alt="Pocoo" /></a>
{%trans%}project{%endtrans%}</p>
<h3>Download</h3>
<p class="download">{%trans%}Current version: <a href="https://pypi.org/project/Sphinx/" alt="PyPI"><img src="https://img.shields.io/pypi/v/sphinx.svg"></a>{%endtrans%}</p>
<p>{%trans%}Install Sphinx with:{%endtrans%}</p>
<pre>pip install -U Sphinx</pre>
<h3>{%trans%}Questions? Suggestions?{%endtrans%}</h3>
<p>{%trans%}Join the <a href="https://groups.google.com/group/sphinx-users">sphinx-users</a> mailing list on Google Groups:{%endtrans%}</p>
<div class="subscribeformwrapper">
<form action="https://groups.google.com/group/sphinx-users/boxsubscribe"
class="subscribeform">
<input type="text" name="email" value="your@email"
onfocus="this.value = ''" />
<input type="submit" name="sub" value="Subscribe" />
</form>
</div>
<p>{%trans%}or come to the <tt>#sphinx-doc</tt> channel on <a href="https://web.libera.chat/?channel=#sphinx-doc">libera.chat</a>.{%endtrans%}</p>
<p>{%trans%}You can also open an issue at the
<a href="https://github.com/sphinx-doc/sphinx/issues">tracker</a>.{%endtrans%}</p>

105
doc/_themes/sphinx13/layout.html vendored
View File

@@ -1,75 +1,60 @@
{#
sphinxdoc/layout.html
~~~~~~~~~~~~~~~~~~~~~
Sphinx layout template for the sphinxdoc theme.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{# Sphinx layout template for the sphinxdoc theme. #}
{%- extends "basic/layout.html" %}
{# put the sidebar before the body #}
{% block sidebar1 %}{{ sidebar() }}{% endblock %}
{% block sidebar2 %}{% endblock %}
{% block extrahead %}
<link href='https://fonts.googleapis.com/css?family=Open+Sans:300,400,700'
rel='stylesheet' type='text/css' />
{{ super() }}
{%- if not embedded %}
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
{% if pagename == 'index' %}
.related { display: none; }
{% endif %}
</style>
<script>
// intelligent scrolling of the sidebar content
window.onscroll = () => {
const sb = document.getElementsByClassName('sphinxsidebarwrapper')[0]
const sbh = sb.offsetHeight
const offset = document.getElementsByClassName('sphinxsidebar')[0].offsetTop;
const wintop = window.scrollTop;
const winbot = wintop + window.offsetHeight
const curtop = sb.offsetTop;
const curbot = curtop + sbh;
// does sidebar fit in window?
if (sbh < window.offsetHeight) {
// yes: easy case -- always keep at the top
sb.style.top = Math.min(Math.max(0, wintop - offset - 10), window.innerHeight - sbh - 200)
} else {
// no: only scroll if top/bottom edge of sidebar is at
// top/bottom edge of window
if (curtop > wintop && curbot > winbot) {
sb.style.top = Math.max(wintop - offset - 10, 0)
} else if (curtop < wintop && curbot < winbot) {
sb.style.top = Math.min(winbot - sbh - offset - 20, window.innerHeight - sbh - 200)
}
}
}
</script>
{%- if not embedded and pagename == 'index' %}
<style>.related { display: none; }</style>
{%- endif %}
{% endblock %}
{% block rootrellink %}
<li><a href="{{ pathto('index') }}">Sphinx home</a>&#160;|</li>
<li><a href="{{ pathto('contents') }}">Documentation</a> &#187;</li>
{% endblock %}
{% block header %}
<div class="pageheader">
<ul>
<li><a href="{{ pathto('index') }}">Home</a></li>
<li><a href="{{ pathto('usage/installation') }}">Get it</a></li>
<li><a href="{{ pathto('contents') }}">Docs</a></li>
<li><a href="{{ pathto('development/index') }}">Extend</a></li>
</ul>
<div>
<a href="{{ pathto('index') }}">
<img src="{{ pathto('_static/sphinxheader.png', 1) }}" alt="SPHINX" />
</a>
</div>
{% endblock %}
{%- block relbar1 %}
<div class="related" role="navigation" aria-label="related navigation">
<h3>{{ _('Navigation') }}</h3>
<ul>
<li><a href="{{ pathto('index') }}">Documentation</a> &raquo;</li>
{%- for parent in parents %}
<li class="nav-item nav-item-{{ loop.index }}"><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a>{{ reldelim1 }}</li>
{%- endfor %}
<li class="nav-item nav-item-this"><a href="{{ link|e }}">{{ title }}</a></li>
</ul>
</div>
{% endblock %}
{%- block content %}
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
{%- include "searchbox.html" %}
<div>
<h3>{{ _('Contents') }}</h3>
{%- if pagename != "index" %}
{{ toc }}
{%- else %}
{{ toctree(includehidden=True, maxdepth=3) }}
{%- endif %}
</div>
</div>
{%- block document %}
<div class="body" role="main">
{% block body %}{% endblock %}
</div>
{%- endblock %}
</div>
{%- endblock %}
{%- block relbar2 %}{% endblock %}
{%- block footer %}
<div class="footer" role="contentinfo">
{% trans path=pathto('copyright'), copyright=copyright|e %}&#169; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
{% trans sphinx_version=sphinx_version|e %}Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
</div>
{%- endblock %}

BIN
doc/_themes/sphinx13/static/bodybg.png vendored
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 429 B

BIN
doc/_themes/sphinx13/static/footerbg.png vendored
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 180 B

BIN
doc/_themes/sphinx13/static/headerbg.png vendored
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 189 B

BIN
doc/_themes/sphinx13/static/listitem.png vendored
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 149 B

BIN
doc/_themes/sphinx13/static/relbg.png vendored
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 183 B

220
doc/_themes/sphinx13/static/sphinx13.css vendored
View File

@@ -1,187 +1,74 @@
/*
* sphinx13.css
* ~~~~~~~~~~~~
*
* Sphinx stylesheet -- sphinx13 theme.
*
* :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/* Stylesheet for Sphinx's documentation */
@import url("basic.css");
/* -- page layout ----------------------------------------------------------- */
/* Set master colours */
:root {
--fonts-sans-serif: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
--colour-sphinx-blue: #0A507A;
--colour-text: #333;
--colour-links-light: #057;
}
body {
font-family: 'Open Sans', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
'Verdana', sans-serif;
font-size: 14px;
text-align: center;
background-image: url(bodybg.png);
color: black;
padding: 0;
border-right: 1px solid #0a507a;
border-left: 1px solid #0a507a;
font-family: var(--fonts-sans-serif);
margin: 0 auto;
min-width: 780px;
max-width: 1080px;
color: var(--colour-text);
}
.pageheader {
background-image: url(headerbg.png);
text-align: left;
background-color: var(--colour-sphinx-blue);
padding: 10px 15px;
}
.pageheader ul {
float: right;
color: white;
list-style-type: none;
padding-left: 0;
margin-top: 30px;
margin-right: 10px;
}
.pageheader li {
float: left;
margin: 0 0 0 10px;
}
.pageheader li a {
border-radius: 1px;
padding: 8px 12px;
color: #f9f9f0;
text-shadow: 0 0 5px rgba(0, 0, 0, 0.5);
}
.pageheader li a:hover {
background-color: #f9f9f0;
color: #0a507a;
text-shadow: none;
}
div.document {
background-color: white;
text-align: left;
}
div.bodywrapper {
margin: 0 240px 0 0;
border-right: 1px solid #0a507a;
display: flex;
margin: 0 0.5em;
}
div.body {
border-left: 1px solid var(--colour-sphinx-blue);
margin: 0;
padding: 0.5em 20px 20px 20px;
padding: 0.5em 1.25em;
min-width: 0;
max-width: 800px;
}
div.related {
font-size: 1em;
display: flex;
color: white;
}
div.related ul {
background-image: url(relbg.png);
height: 1.9em;
background-color: var(--colour-sphinx-blue);
border-top: 1px solid #002e50;
border-bottom: 1px solid #002e50;
}
div.related ul li {
margin: 0 5px 0 0;
padding: 0;
float: left;
}
div.related ul li.right {
float: right;
margin-right: 5px;
}
div.related ul li a {
margin: 0;
padding: 0 5px 0 5px;
line-height: 1.75em;
color: #f9f9f0;
text-shadow: 0px 0px 1px rgba(0, 0, 0, 0.5);
color: white;
}
div.related ul li a:hover {
color: white;
/*text-decoration: underline;*/
text-shadow: 0px 0px 1px rgba(255, 255, 255, 0.5);
text-shadow: 0 0 1px rgba(255, 255, 255, 0.5);
}
div.sphinxsidebarwrapper {
position: relative;
top: 0px;
padding: 0;
}
div.sphinxsidebar {
overflow-wrap: break-word;
margin: 0;
padding: 0 15px 15px 0;
padding-right: 15px;
width: 210px;
float: right;
font-size: 1em;
text-align: left;
max-height: 0px;
}
div.sphinxsidebar .logo {
font-size: 1.8em;
color: #0A507A;
font-weight: 300;
text-align: center;
}
div.sphinxsidebar .logo img {
vertical-align: middle;
}
div.sphinxsidebar .download a img {
vertical-align: middle;
}
div.subscribeformwrapper {
display: block;
overflow: auto;
margin-bottom: 1.2em;
}
div.sphinxsidebar input {
border: 1px solid #aaa;
font-family: 'Open Sans', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
'Verdana', sans-serif;
}
div.sphinxsidebar .subscribeform {
margin-top: 0;
}
div.sphinxsidebar .subscribeform input {
border: 1px solid #aaa;
font-size: 0.9em;
float: left;
padding: 0.25em 0.5em;
box-sizing: border-box;
}
div.sphinxsidebar .subscribeform input[type="text"] {
width: 60%;
}
div.sphinxsidebar .subscribeform input[type="submit"] {
width: 40%;
border-left: none;
}
div.sphinxsidebar h3 {
font-size: 1.5em;
border-top: 1px solid #0a507a;
margin-top: 1em;
margin-top: 0;
margin-bottom: 0.5em;
padding-top: 0.5em;
}
@@ -198,12 +85,6 @@ div.sphinxsidebar h3, div.sphinxsidebar h4 {
padding-left: 14px;
color: #333;
font-weight: 300;
/*text-shadow: 0px 0px 0.5px rgba(0, 0, 0, 0.4);*/
}
div.sphinxsidebarwrapper > h3:first-child {
margin-top: 0.5em;
border: none;
}
div.sphinxsidebar h3 a {
@@ -219,17 +100,16 @@ div.sphinxsidebar ul {
div.sphinxsidebar ul ul {
margin-left: 20px;
list-style-image: url(listitem.png);
list-style-type: none;
}
div.footer {
background-image: url(footerbg.png);
background-color: var(--colour-sphinx-blue);
color: #ccc;
text-shadow: 0 0 .2px rgba(255, 255, 255, 0.8);
padding: 3px 8px 3px 0;
clear: both;
font-size: 0.8em;
text-align: right;
}
/* no need to make a visible link to Sphinx on the Sphinx page */
@@ -244,14 +124,10 @@ p {
}
a {
color: #A2881D;
color: var(--colour-links-light);
text-decoration: none;
}
a:hover {
color: #E1C13F;
}
div.body a {
text-decoration: underline;
}
@@ -259,12 +135,18 @@ div.body a {
h1 {
margin: 10px 0 0 0;
font-size: 2.4em;
color: #0A507A;
color: var(--colour-sphinx-blue);
font-weight: 300;
}
h1 span.pre {
/* for code in titles */
word-break: break-all;
white-space: normal;
}
h2 {
margin: 1.em 0 0.2em 0;
margin: 1em 0 0.2em 0;
font-size: 1.5em;
font-weight: 300;
padding: 0;
@@ -282,12 +164,12 @@ div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.b
}
div.body h1 a tt, div.body h2 a tt, div.body h3 a tt, div.body h4 a tt, div.body h5 a tt, div.body h6 a tt {
color: #0A507A !important;
color: var(--colour-sphinx-blue) !important;
font-size: inherit !important;
}
a.headerlink {
color: #0A507A !important;
color: var(--colour-sphinx-blue) !important;
font-size: 12px;
margin-left: 6px;
padding: 0 4px 0 4px;
@@ -308,7 +190,7 @@ h1 code, h2 code, h3 code, h4 code {
cite, code, tt {
font-family: 'Consolas', 'DejaVu Sans Mono',
'Bitstream Vera Sans Mono', monospace;
font-size: 14px;
font-size: 1em;
letter-spacing: -0.02em;
}
@@ -335,17 +217,13 @@ hr {
a tt {
border: 0;
color: #a2881d;
}
a tt:hover {
color: #e1c13f;
color: var(--colour-links-light);
}
pre {
font-family: 'Consolas', 'Courier New', 'DejaVu Sans Mono',
'Bitstream Vera Sans Mono', monospace;
font-size: 13px;
font-size: 1em;
letter-spacing: 0.015em;
line-height: 120%;
padding: 0.5em;
@@ -428,8 +306,7 @@ div.admonition div.highlight {
}
.viewcode-back {
font-family: 'Open Sans', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
'Verdana', sans-serif;
font-family: var(--fonts-sans-serif);
}
div.viewcode-block:target {
@@ -438,8 +315,15 @@ div.viewcode-block:target {
border-bottom: 1px solid #ac9;
}
.contentstable {
margin-left: 30px;
margin: 0 auto;
table-layout: fixed;
/* media queries */
/* Reduce padding & margins for smaller screens */
@media (max-width: 750px) {
.sphinxsidebar {
display: none;
}
div.body {
border-left: none;
}
}

2
doc/_themes/sphinx13/theme.conf vendored
View File

@@ -1,4 +1,4 @@
[theme]
inherit = basic
stylesheet = sphinx13.css
pygments_style = default
sidebars =

24
doc/conf.py
View File

@@ -2,6 +2,7 @@
import os
import re
import time
import sphinx
@@ -10,23 +11,25 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
'sphinx.ext.intersphinx',
'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram']
root_doc = 'contents'
templates_path = ['_templates']
exclude_patterns = ['_build']
project = 'Sphinx'
copyright = '2007-2022, Georg Brandl and the Sphinx team'
copyright = f'2007-{time.strftime("%Y")}, the Sphinx developers'
version = sphinx.__display_version__
release = version
show_authors = True
html_theme = 'sphinx13'
html_theme_path = ['_themes']
html_css_files = [
# 'basic.css', # included through inheritance from the basic theme
'sphinx13.css',
]
modindex_common_prefix = ['sphinx.']
html_static_path = ['_static']
html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}
html_title = 'Sphinx documentation'
html_additional_pages = {'index': 'index.html'}
html_additional_pages = {'contents': 'contents.html'}
html_use_opensearch = 'https://www.sphinx-doc.org/en/master'
html_baseurl = 'https://www.sphinx-doc.org/en/master/'
html_favicon = '_static/favicon.svg'
@@ -35,7 +38,7 @@ htmlhelp_basename = 'Sphinxdoc'
epub_theme = 'epub'
epub_basename = 'sphinx'
epub_author = 'Georg Brandl'
epub_author = 'the Sphinx developers'
epub_publisher = 'https://www.sphinx-doc.org/'
epub_uid = 'web-site'
epub_scheme = 'url'
@@ -52,11 +55,10 @@ epub_fix_images = False
epub_max_image_width = 0
epub_show_urls = 'inline'
epub_use_index = False
epub_guide = (('toc', 'contents.xhtml', 'Table of Contents'),)
epub_description = 'Sphinx documentation generator system manual'
latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
'Georg Brandl', 'manual', 1)]
latex_documents = [('index', 'sphinx.tex', 'Sphinx Documentation',
'the Sphinx developers', 'manual', 1)]
latex_logo = '_static/sphinx.png'
latex_elements = {
'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}',
@@ -94,8 +96,8 @@ extlinks = {'duref': ('https://docutils.sourceforge.io/docs/ref/rst/'
'directives.html#%s', '%s')}
man_pages = [
('contents', 'sphinx-all', 'Sphinx documentation generator system manual',
'Georg Brandl', 1),
('index', 'sphinx-all', 'Sphinx documentation generator system manual',
'the Sphinx developers', 1),
('man/sphinx-build', 'sphinx-build', 'Sphinx documentation generator tool',
'', 1),
('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation '
@@ -107,7 +109,7 @@ man_pages = [
]
texinfo_documents = [
('contents', 'sphinx', 'Sphinx Documentation', 'Georg Brandl',
('index', 'sphinx', 'Sphinx Documentation', 'the Sphinx developers',
'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools',
1),
]

39
doc/contents.rst
View File

@@ -1,39 +0,0 @@
.. _contents:
Sphinx documentation contents
=============================
.. toctree::
:maxdepth: 2
usage/index
tutorial/index
development/index
man/index
templating
latex
extdev/index
internals/index
faq
glossary
changes
examples
Indices and tables
==================
.. only:: builder_html
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
* :ref:`glossary`
.. only:: not builder_html
* :ref:`modindex`
* :ref:`glossary`

101
doc/index.rst Normal file
View File

@@ -0,0 +1,101 @@
=======
Welcome
=======
**Sphinx makes it easy to create intelligent and beautiful documentation.**
Install
=======
Install Sphinx with ``pip install -U Sphinx``. See :doc:`usage/installation` for
further details.
Features
========
* **Output formats:** HTML (including Windows HTML Help), LaTeX (for printable
PDF versions), ePub, Texinfo, manual pages, plain text
* **Extensive cross-references:** semantic markup and automatic links for
functions, classes, citations, 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 language-specific module
indices
* **Code handling:** automatic highlighting using the Pygments_ highlighter
* **Extensions:** automatic testing of code snippets, inclusion of docstrings
from Python modules (API docs), and :ref:`more <builtin-extensions>`
* **Contributed extensions:** dozens of extensions
:ref:`contributed by users <third-party-extensions>`; most of them installable
from PyPI
.. _Pygments: https://pygments.org/
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_.
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Docutils: https://docutils.sourceforge.io/
Documentation
=============
* :doc:`First steps with Sphinx <usage/quickstart>`: overview of basic tasks
* :doc:`Tutorial <tutorial/index>`: beginners tutorial
* :ref:`Search page <search>`: search the documentation
* :doc:`Changes <changes>`: release history
* :ref:`General Index <genindex>`: all functions, classes, terms
* :ref:`Python Module Index <modindex>`: the index of Python modules
* :doc:`Glossary <glossary>`: definitions of various terms
* :doc:`Sphinx's Authors <internals/authors>`: the Sphinx developers
* `Contents <contents.html>`__: full table of contents
Support
=======
For questions or to report problems with Sphinx, join the `sphinx-users`_
mailing list on Google Groups, come to the ``#sphinx-doc`` channel on
`libera.chat`_, or open an issue at the tracker_.
.. _sphinx-users: https://groups.google.com/group/sphinx-users
.. _libera.chat: https://web.libera.chat/?channel=#sphinx-doc
.. _tracker: https://github.com/sphinx-doc/sphinx/issues
Examples of other projects using Sphinx can be found in the :doc:`examples page
<examples>`. A useful tutorial_ has been written by the matplotlib developers.
.. _tutorial: http://matplotlib.sourceforge.net/sampledoc/
There is a translation team in Transifex_ of this documentation, thanks to the
Sphinx document translators.
.. _Transifex: https://www.transifex.com/sphinx-doc/sphinx-doc/dashboard/
Contributor guide
=================
See the :doc:`Sphinx contributors' guide <internals/contributing>` if you would
like to contribute to the project.
.. master toctree:
.. toctree::
:maxdepth: 5
:hidden:
usage/index
tutorial/index
development/index
man/index
templating
latex
extdev/index
internals/index
faq
glossary
changes
examples

4
doc/tutorial/end.rst
View File

@@ -2,5 +2,5 @@ Where to go from here
=====================
This tutorial covered the very first steps to create a documentation project
with Sphinx. To continue learning more about Sphinx, check out the :ref:`rest
of the documentation <contents>`.
with Sphinx. To continue learning more about Sphinx, check out the `rest of the
documentation <../contents.html>`__.

2
tox.ini
View File

@@ -75,7 +75,7 @@ description =
extras =
docs
commands =
python -X dev -X warn_default_encoding -m sphinx -M html ./doc ./build/sphinx -W
python -X dev -X warn_default_encoding -m sphinx -M html ./doc ./build/sphinx -W --keep-going
[testenv:docslint]
basepython = python3