mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Update documentation structure and theming (#10677)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
This commit is contained in:
Chris Holdgraf
GitHub
parent
a504ac6100
commit
eb0a6c574f
12
doc/_themes/sphinx13/layout.html
vendored
12
doc/_themes/sphinx13/layout.html
vendored
@ -33,13 +33,13 @@
|
||||
<div class="document">
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
{%- include "searchbox.html" %}
|
||||
<div>
|
||||
<h3>{{ _('Contents') }}</h3>
|
||||
{%- if pagename != "index" %}
|
||||
<div class="sphinxsidebar-navigation__contents">
|
||||
<h3>{{ _('On this page') }}</h3>
|
||||
{{ toc }}
|
||||
{%- else %}
|
||||
{{ toctree(includehidden=True, maxdepth=3) }}
|
||||
{%- endif %}
|
||||
</div>
|
||||
<div class="sphinxsidebar-navigation__pages">
|
||||
<h3>{{ _('Site navigation') }}</h3>
|
||||
{{ toctree(includehidden=True, maxdepth=3, titles_only=True) }}
|
||||
</div>
|
||||
</div>
|
||||
{%- block document %}
|
||||
|
||||
44
doc/_themes/sphinx13/static/sphinx13.css
vendored
44
doc/_themes/sphinx13/static/sphinx13.css
vendored
@ -27,7 +27,7 @@ div.document {
|
||||
div.body {
|
||||
border-left: 1px solid var(--colour-sphinx-blue);
|
||||
margin: 0;
|
||||
padding: 0.5em 1.25em;
|
||||
padding: 0.5em 1.75em;
|
||||
min-width: 0;
|
||||
max-width: 800px;
|
||||
}
|
||||
@ -59,10 +59,15 @@ div.sphinxsidebarwrapper {
|
||||
}
|
||||
|
||||
div.sphinxsidebar {
|
||||
position: sticky;
|
||||
top: 0;
|
||||
align-self: flex-start;
|
||||
height: 100vh;
|
||||
width: 250px;
|
||||
overflow-y: auto;
|
||||
overflow-wrap: break-word;
|
||||
margin: 0;
|
||||
padding-right: 15px;
|
||||
width: 210px;
|
||||
font-size: 1em;
|
||||
}
|
||||
|
||||
@ -99,8 +104,27 @@ div.sphinxsidebar ul {
|
||||
}
|
||||
|
||||
div.sphinxsidebar ul ul {
|
||||
margin-left: 20px;
|
||||
margin-left: 1rem;
|
||||
list-style-type: none;
|
||||
font-size: .9em;
|
||||
}
|
||||
|
||||
/* De-dent the first list because we hide the top-level item */
|
||||
.sphinxsidebar .sphinxsidebar-navigation__contents > ul > li > ul {
|
||||
margin-left: 0;
|
||||
}
|
||||
|
||||
div.sphinxsidebar p.caption {
|
||||
font-weight: 300;
|
||||
font-size: 1.2rem;
|
||||
}
|
||||
|
||||
div.sphinxsidebar li.current > a {
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.sphinxsidebar-navigation__contents > ul > li > a {
|
||||
display: none;
|
||||
}
|
||||
|
||||
div.footer {
|
||||
@ -170,11 +194,10 @@ div.body h1 a tt, div.body h2 a tt, div.body h3 a tt, div.body h4 a tt, div.body
|
||||
|
||||
a.headerlink {
|
||||
color: var(--colour-sphinx-blue) !important;
|
||||
font-size: 12px;
|
||||
font-size: .8em;
|
||||
margin-left: 6px;
|
||||
padding: 0 4px 0 4px;
|
||||
text-decoration: none !important;
|
||||
float: right;
|
||||
}
|
||||
|
||||
a.headerlink:hover {
|
||||
@ -250,6 +273,12 @@ div.quotebar {
|
||||
margin-left: 1em;
|
||||
}
|
||||
|
||||
blockquote {
|
||||
font-size: 1.5em;
|
||||
padding-left: 1rem;
|
||||
margin-left: 0;
|
||||
}
|
||||
|
||||
nav.contents,
|
||||
div.topic,
|
||||
aside.topic {
|
||||
@ -271,11 +300,11 @@ div.admonition, div.warning {
|
||||
border: 1px solid #86989B;
|
||||
border-radius: 2px;
|
||||
background-color: #f7f7f7;
|
||||
padding: 0;
|
||||
padding: 1rem;
|
||||
}
|
||||
|
||||
div.admonition > p, div.warning > p {
|
||||
margin: 0.5em 1em 0.5em 1em;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
@ -285,7 +314,6 @@ div.admonition > pre, div.warning > pre {
|
||||
|
||||
div.admonition > p.admonition-title,
|
||||
div.warning > p.admonition-title {
|
||||
margin-top: 0.5em;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
|
||||
133
doc/index.rst
133
doc/index.rst
@ -2,16 +2,9 @@
|
||||
Welcome
|
||||
=======
|
||||
|
||||
**Sphinx makes it easy to create intelligent and beautiful documentation.**
|
||||
.. epigraph:: 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
|
||||
========
|
||||
Here are some of Sphinx's major features:
|
||||
|
||||
* **Output formats:** HTML (including Windows HTML Help), LaTeX (for printable
|
||||
PDF versions), ePub, Texinfo, manual pages, plain text
|
||||
@ -24,78 +17,98 @@ Features
|
||||
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_.
|
||||
from Python modules (API docs) via :ref:`built-in extensions
|
||||
<builtin-extensions>`, and much more functionality via :ref:`third-party
|
||||
extensions <third-party-extensions>`.
|
||||
* **Themes:** modify the look and feel of outputs via :doc:`creating themes
|
||||
<development/theming>`, and re-use many :ref:`third-party themes
|
||||
<third-party-themes>`.
|
||||
* **Contributed extensions:** dozens of extensions :ref:`contributed by users
|
||||
<third-party-extensions>`; most of them installable from PyPI.
|
||||
|
||||
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
|
||||
.. _Docutils: https://docutils.sourceforge.io/
|
||||
.. _Pygments: https://pygments.org/
|
||||
|
||||
Documentation
|
||||
=============
|
||||
Sphinx uses the reStructuredText_ markup language by default, and can read
|
||||
:ref:`MyST markdown <markdown>` via third-party extensions. Both of these
|
||||
are powerful and straightforward to use, and have functionality
|
||||
for complex documentation and publishing workflows. They both build upon
|
||||
Docutils_ to parse and write documents.
|
||||
|
||||
* :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
|
||||
See below for how to navigate Sphinx's documentation.
|
||||
|
||||
Support
|
||||
=======
|
||||
.. seealso::
|
||||
|
||||
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_.
|
||||
The `Sphinx documentation Table of Contents <contents.html>`_ has
|
||||
a full list of this site's pages.
|
||||
|
||||
.. _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
|
||||
.. _get-started:
|
||||
|
||||
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.
|
||||
Get started
|
||||
===========
|
||||
|
||||
.. _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:
|
||||
These sections cover the basics of getting started with Sphinx, including
|
||||
creating and building your own documentation from scratch.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 5
|
||||
:hidden:
|
||||
:maxdepth: 2
|
||||
:caption: Get started
|
||||
|
||||
usage/quickstart
|
||||
usage/installation
|
||||
tutorial/index
|
||||
|
||||
.. _user-guides:
|
||||
|
||||
User Guides
|
||||
===========
|
||||
|
||||
These sections cover various topics in using and extending Sphinx for various
|
||||
use-cases. They are a comprehensive guide to using Sphinx in many contexts and
|
||||
assume more knowledge of Sphinx. If you are new to Sphinx, we recommend
|
||||
starting with :ref:`get-started`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: User Guides
|
||||
|
||||
usage/index
|
||||
tutorial/index
|
||||
development/index
|
||||
man/index
|
||||
|
||||
templating
|
||||
latex
|
||||
extdev/index
|
||||
|
||||
internals/index
|
||||
Community guide
|
||||
===============
|
||||
|
||||
Sphinx is community supported and welcomes contributions from anybody.
|
||||
The sections below should help you get started joining the Sphinx community
|
||||
as well as contributing.
|
||||
|
||||
See the :doc:`Sphinx contributors' guide <internals/contributing>` if you would
|
||||
like to contribute to the project.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Community
|
||||
|
||||
support
|
||||
internals/index
|
||||
faq
|
||||
|
||||
Reference guide
|
||||
===============
|
||||
|
||||
Reference documentation is more complete and programmatic in nature, it is a
|
||||
collection of information that can be quickly referenced. If you would like
|
||||
usecase-driven documentation, see :ref:`get-started` or :ref:`user-guides`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Reference
|
||||
|
||||
man/index
|
||||
glossary
|
||||
changes
|
||||
examples
|
||||
|
||||
@ -7,8 +7,8 @@ feature requests, writing new documentation or submitting patches for new or
|
||||
fixed behavior. This guide serves to illustrate how you can get started with
|
||||
this.
|
||||
|
||||
Getting help
|
||||
------------
|
||||
Get help
|
||||
--------
|
||||
|
||||
The Sphinx community maintains a number of mailing lists and IRC channels.
|
||||
|
||||
@ -46,8 +46,8 @@ and post that instead.
|
||||
.. _`sphinx-dev`: mailto:sphinx-dev@googlegroups.com
|
||||
|
||||
|
||||
Writing code
|
||||
------------
|
||||
Contribute code
|
||||
---------------
|
||||
|
||||
The Sphinx source code is managed using Git and is hosted on `GitHub`__. The
|
||||
recommended way for new contributors to submit code to Sphinx is to fork this
|
||||
@ -57,6 +57,8 @@ before it is merged into the main repository.
|
||||
|
||||
.. __: https://github.com/sphinx-doc/sphinx
|
||||
|
||||
.. _contribute-get-started:
|
||||
|
||||
Getting started
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
@ -235,15 +237,38 @@ If you want to know more detailed usage, please refer to ``tests/conftest.py``
|
||||
and other ``test_*.py`` files under ``tests`` directory.
|
||||
|
||||
|
||||
Writing documentation
|
||||
---------------------
|
||||
Contribute documentation
|
||||
------------------------
|
||||
|
||||
Contributing to documentation involves modifying the source files found in the
|
||||
``doc/`` folder. To get started, you should first follow :ref:`contribute-get-started`,
|
||||
and then take the steps below to work with the documentation.
|
||||
|
||||
The following sections describe how to get started with contributing
|
||||
documentation, as well as key aspects of a few different tools that we use.
|
||||
|
||||
.. todo:: Add a more extensive documentation contribution guide.
|
||||
|
||||
You can build documentation using ``tox``::
|
||||
Build the documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
We use `the tox tool <https://tox.wiki/en/latest/>`__ to quickly build the
|
||||
documentation. Tox is kind-of like a Makefile, but includes the ability to
|
||||
intsall an isolated environment used to run each task.
|
||||
|
||||
To build the documentation with ``tox``, run the following command::
|
||||
|
||||
tox -e docs
|
||||
|
||||
This will parse the Sphinx documentation's source files and generate HTML for
|
||||
you to preview in ``build/sphinx/html``.
|
||||
|
||||
You can also build a **live version of the documentation** that you can preview
|
||||
in the browser. It will detect changes and reload the page any time you make
|
||||
edits. To do so, run the following command::
|
||||
|
||||
tox -e docs-live
|
||||
|
||||
Translations
|
||||
~~~~~~~~~~~~
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
================
|
||||
Sphinx internals
|
||||
================
|
||||
====================
|
||||
Contribute to Sphinx
|
||||
====================
|
||||
|
||||
This guide contains information about the Sphinx open source project itself.
|
||||
This is where you can find information about how Sphinx is managed and learn
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
Man Pages
|
||||
=========
|
||||
Command-Line Tools
|
||||
==================
|
||||
|
||||
These are the applications provided as part of Sphinx.
|
||||
|
||||
|
||||
20
doc/support.rst
Normal file
20
doc/support.rst
Normal file
@ -0,0 +1,20 @@
|
||||
Get 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/
|
||||
@ -1,8 +1,8 @@
|
||||
.. _tutorial:
|
||||
|
||||
===============
|
||||
Sphinx tutorial
|
||||
===============
|
||||
========================
|
||||
Build your first project
|
||||
========================
|
||||
|
||||
In this tutorial you will build a simple documentation project using Sphinx, and
|
||||
view it in your browser as HTML. The project will include narrative,
|
||||
|
||||
@ -10,8 +10,6 @@ looking for guidance on extending Sphinx, refer to :doc:`/development/index`.
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
quickstart
|
||||
installation
|
||||
restructuredtext/index
|
||||
markdown
|
||||
configuration
|
||||
|
||||
@ -345,10 +345,12 @@ These themes are:
|
||||
available, however it will emit a notice that it is an alias for the new
|
||||
'alabaster' theme.
|
||||
|
||||
.. _third-party-themes:
|
||||
|
||||
Third Party Themes
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
There are many third-party themes available for Sphinx. Some of these are for
|
||||
There are many third-party themes created for Sphinx. Some of these are for
|
||||
general use, while others are specific to an individual project.
|
||||
|
||||
sphinx-themes.org__ is a gallery that showcases various themes for Sphinx,
|
||||
|
||||
11
tox.ini
11
tox.ini
@ -86,6 +86,17 @@ extras =
|
||||
commands =
|
||||
sphinx-lint --enable line-too-long --max-line-length 85 CHANGES CONTRIBUTING.rst README.rst doc/
|
||||
|
||||
[testenv:docs-live]
|
||||
basepython = python3
|
||||
description =
|
||||
Build documentation.
|
||||
extras =
|
||||
docs
|
||||
deps =
|
||||
sphinx-autobuild
|
||||
commands =
|
||||
sphinx-autobuild ./doc ./build/sphinx/
|
||||
|
||||
[testenv:twine]
|
||||
basepython = python3
|
||||
description =
|
||||
|
||||
Loading…
Reference in New Issue
Block a user