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

[docs] Improve landing page (#12453)

Browse Source 
This commit is intended to improve new user's first-interaction with the Sphinx site:

- Make page header icon/text smaller and not capitalized
- Give min-width to left sidebar (it was getting too small at certain window sizes)
- Replace features list on landing page with admonition boxes, with adaptive layout
- Add landing page "used by" section
- Slightly restructure the Extension section, into Tutorials and How-tos
- Add code to `conf.py` to write HTML write redirect pages for moved documents
- Improve support page, by adding link to Stackoverflow, GH discussion and ReadtheDocs,
  and remove defunct link to libera chat and matplotlib tutorial
This commit is contained in:
Chris Sewell
2024-06-21 20:12:57 +02:00
committed by GitHub
parent bc1a5c5c88
commit 8f97fd276a
22 changed files with 271 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/_static/jupyter-logo.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 126 KiB

BIN
doc/_static/linux-logo.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 602 KiB

BIN
doc/_static/python-logo.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 183 KiB

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

@@ -29,7 +29,7 @@ body {
} }
.pageheader a { .pageheader a {
width: 5%; width: 2em;
} }
.pageheader img { .pageheader img {
@@ -39,10 +39,9 @@ body {
.pageheader h1{ .pageheader h1{
color: white; color: white;
margin: 0; margin: 0;
font-weight: 600; font-weight: 400;
font-size: 3.5rem; font-size: 2em;
line-height: 1; line-height: 1;
font-variant: small-caps;
} }
div.document { div.document {
@@ -90,6 +89,7 @@ div.sphinxsidebar {
align-self: flex-start; align-self: flex-start;
height: 100vh; height: 100vh;
width: 250px; width: 250px;
min-width: 150px;
overflow-y: auto; overflow-y: auto;
overflow-wrap: break-word; overflow-wrap: break-word;
margin: 0; margin: 0;
@@ -339,7 +339,7 @@ div.admonition, div.warning {
font-size: 0.9em; font-size: 0.9em;
margin: 1em 0 1em 0; margin: 1em 0 1em 0;
border: 1px solid #86989B; border: 1px solid #86989B;
border-radius: 2px; border-radius: 3px;
background-color: #f7f7f7; background-color: #f7f7f7;
padding: 1rem; padding: 1rem;
} }
@@ -356,9 +356,10 @@ div.admonition > pre, div.warning > pre {
div.admonition > p.admonition-title, div.admonition > p.admonition-title,
div.warning > p.admonition-title { div.warning > p.admonition-title {
font-weight: bold; font-weight: bold;
background-color: #ddd; background-color: #dddddd;
margin: -1rem -1rem 0.8rem -1rem; margin: -1rem -1rem 0.8rem -1rem;
padding: 0.3rem 1rem; padding: 0.3rem 1rem;
border-radius: 3px 3px 0 0;
} }
div.important > p.admonition-title, div.important > p.admonition-title,
@@ -412,7 +413,7 @@ div.viewcode-block:target {
/* media queries */ /* media queries */
/* Reduce padding & margins for smaller screens */ /* Reduce padding & margins for smaller screens */
@media (max-width: 750px) { @media (max-width: 768px) {
.sphinxsidebar { .sphinxsidebar {
display: none; display: none;
} }
@@ -420,3 +421,46 @@ div.viewcode-block:target {
border-left: none; border-left: none;
} }
} }
/* Landing page */
.sphinx-tagline * {
hyphens: none !important;
font-style: italic !important;
}
/* By default align the sphinx-features one per-row and center them,
then for larger screens align them two per-row. */
.sphinx-features {
display: flex;
flex-wrap: wrap;
gap: 10px;
justify-content: center;
}
.sphinx-feature {
flex: 1 1 100%;
margin: 0 !important;
background-color: white !important;
}
.sphinx-feature p {
hyphens: none !important;
}
.sphinx-feature > p.admonition-title {
background-color: #f7f7f7 !important;
}
@media (min-width: 768px) {
.sphinx-feature {
flex: 0 0 auto;
box-sizing: border-box;
width: 48%;
}
}
.sphinx-users {
text-align: center;
font-weight: 500;
}
.sphinx-users-logos {
display: flex;
flex-wrap: wrap;
justify-content: center;
gap: 10px;
}

42
doc/conf.py
View File

@@ -1,11 +1,11 @@
# Sphinx documentation build configuration file # Sphinx documentation build configuration file
from __future__ import annotations
import os import os
import re import re
import time import time
import sphinx import sphinx
from sphinx.application import Sphinx
os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1' os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1'
@@ -236,6 +236,7 @@ nitpick_ignore = {
# -- Extension interface ------------------------------------------------------- # -- Extension interface -------------------------------------------------------
from sphinx import addnodes # NoQA: E402 from sphinx import addnodes # NoQA: E402
from sphinx.application import Sphinx # NoQA: E402, TCH001
event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)') event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
@@ -276,12 +277,51 @@ def linkify_issues_in_changelog(app, docname, source):
source[0] = source[0].replace('.. include:: ../CHANGES.rst', linkified_changelog) source[0] = source[0].replace('.. include:: ../CHANGES.rst', linkified_changelog)
REDIRECT_TEMPLATE = """
<html>
<head>
<noscript>
<meta http-equiv="refresh" content="0; url={{rel_url}}"/>
</noscript>
</head>
<body>
<script>
window.location.href = '{{rel_url}}' + (window.location.search || '') + (window.location.hash || '');
</script>
<p>You should have been redirected.</p>
<a href="{{rel_url}}">If not, click here to continue.</a>
</body>
</html>
""" # noqa: E501
def build_redirects(app: Sphinx, exception: Exception | None) -> None:
# this is a very simple implementation of
# https://github.com/wpilibsuite/sphinxext-rediraffe/blob/main/sphinxext/rediraffe.py
# to re-direct some old pages to new ones
if exception is not None or app.builder.name != 'html':
return
for page, rel_redirect in (
(('development', 'overview.html'), 'index.html'),
(('development', 'builders.html'), 'howtos/builders.html'),
(('development', 'theming.html'), 'html_themes/index.html'),
(('development', 'templating.html'), 'html_themes/templating.html'),
):
path = app.outdir.joinpath(*page)
if path.exists():
continue
path.parent.mkdir(parents=True, exist_ok=True)
with path.open('w', encoding='utf-8') as f:
f.write(REDIRECT_TEMPLATE.replace('{{rel_url}}', rel_redirect))
def setup(app: Sphinx) -> None: def setup(app: Sphinx) -> None:
from sphinx.ext.autodoc import cut_lines from sphinx.ext.autodoc import cut_lines
from sphinx.util.docfields import GroupedField from sphinx.util.docfields import GroupedField
app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
app.connect('source-read', linkify_issues_in_changelog) app.connect('source-read', linkify_issues_in_changelog)
app.connect('build-finished', build_redirects)
app.add_object_type( app.add_object_type(
'confval', 'confval',
'confval', 'confval',

0
doc/development/builders.rst → doc/development/howtos/builders.rst
View File

8
doc/development/howtos/index.rst Normal file
View File

@@ -0,0 +1,8 @@
How-tos
=======
.. toctree::
:maxdepth: 1
setup_extension
builders

13
doc/development/overview.rst → doc/development/howtos/setup_extension.rst
View File

@@ -1,10 +1,5 @@
Developing extensions overview Depend on another extension
============================== ===========================
This page contains general information about developing Sphinx extensions.
Make an extension depend on another extension
---------------------------------------------
Sometimes your extension depends on the functionality of another Sometimes your extension depends on the functionality of another
Sphinx extension. Most Sphinx extensions are activated in a Sphinx extension. Most Sphinx extensions are activated in a
@@ -19,12 +14,12 @@ use the :meth:`sphinx.application.Sphinx.setup_extension` method. This will
activate another extension at run-time, ensuring that you have access to its activate another extension at run-time, ensuring that you have access to its
functionality. functionality.
For example, the following code activates the ``recommonmark`` extension: For example, the following code activates the :mod:`sphinx.ext.autodoc` extension:
.. code-block:: python .. code-block:: python
def setup(app): def setup(app):
app.setup_extension("recommonmark") app.setup_extension('sphinx.ext.autodoc')
.. note:: .. note::

7
doc/development/theming.rst → doc/development/html_themes/index.rst
View File

@@ -1,3 +1,5 @@
.. _extension-html-theme:
HTML theme development HTML theme development
====================== ======================
@@ -222,6 +224,11 @@ If your theme package contains two or more themes, please call
Templating Templating
---------- ----------
.. toctree::
:hidden:
templating
The :doc:`guide to templating <templating>` is helpful if you want to write your The :doc:`guide to templating <templating>` is helpful if you want to write your
own templates. What is important to keep in mind is the order in which Sphinx own templates. What is important to keep in mind is the order in which Sphinx
searches for templates: searches for templates:

0
doc/development/templating.rst → doc/development/html_themes/templating.rst
View File

29
doc/development/index.rst
View File

@@ -1,24 +1,19 @@
========================= .. _extending-sphinx:
Writing Sphinx Extensions
========================= Extending Sphinx
================
This guide is aimed at giving a quick introduction for those wishing to This guide is aimed at giving a quick introduction for those wishing to
develop their own extensions for Sphinx. Sphinx possesses significant develop their own extensions for Sphinx.
extensibility capabilities including the ability to hook into almost every Sphinx possesses significant extensibility capabilities
point of the build process. If you simply wish to use Sphinx with existing including the ability to hook into almost every point of the build process.
extensions, refer to :doc:`/usage/index`. For a more detailed discussion of If you simply wish to use Sphinx with existing extensions,
the extension interface see :doc:`/extdev/index`. refer to :doc:`/usage/index`.
For a more detailed discussion of the extension interface see :doc:`/extdev/index`.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
overview
tutorials/index tutorials/index
builders howtos/index
html_themes/index
.. toctree::
:caption: Theming
:maxdepth: 2
templating
theming

2
doc/development/tutorials/helloworld.rst
View File

@@ -5,7 +5,7 @@ The objective of this tutorial is to create a very basic extension that adds a
new directive. This directive will output a paragraph containing "hello world". new directive. This directive will output a paragraph containing "hello world".
Only basic information is provided in this tutorial. For more information, refer Only basic information is provided in this tutorial. For more information, refer
to the :doc:`other tutorials <index>` that go into more details. to the :ref:`other tutorials <extension-tutorials-index>` that go into more details.
.. warning:: .. warning::

11
doc/development/tutorials/index.rst
View File

@@ -1,17 +1,12 @@
.. _extension-tutorials-index: .. _extension-tutorials-index:
Extension tutorials Tutorials
=================== =========
Refer to the following tutorials to get started with extension development.
.. toctree:: .. toctree::
:caption: Directive tutorials :maxdepth: 2
:maxdepth: 1
helloworld helloworld
todo todo
recipe recipe
autodoc_ext autodoc_ext

6
doc/extdev/index.rst
View File

@@ -1,7 +1,7 @@
.. _dev-extensions: .. _dev-extensions:
Sphinx Extensions API Sphinx API
===================== ==========
Since many projects will need special features in their documentation, Sphinx Since many projects will need special features in their documentation, Sphinx
is designed to be extensible on several levels. is designed to be extensible on several levels.
@@ -85,7 +85,7 @@ extension. These are:
The config is available as ``app.config`` or ``env.config``. The config is available as ``app.config`` or ``env.config``.
To see an example of use of these objects, refer to To see an example of use of these objects, refer to
:doc:`../development/tutorials/index`. :ref:`the tutorials <extension-tutorials-index>`.
.. _build-phases: .. _build-phases:

2
doc/faq.rst
View File

@@ -30,7 +30,7 @@ How do I...
``sidebartoc`` block. ``sidebartoc`` block.
... write my own extension? ... write my own extension?
See the :doc:`/development/tutorials/index`. See the :ref:`extension-tutorials-index`.
... convert from my existing docs using MoinMoin markup? ... convert from my existing docs using MoinMoin markup?
The easiest way is to convert to xhtml, then convert `xhtml to reST`_. The easiest way is to convert to xhtml, then convert `xhtml to reST`_.

146
doc/index.rst
View File

@@ -1,40 +1,116 @@
======= ======
Welcome Sphinx
======= ======
.. epigraph:: Sphinx makes it easy to create intelligent and beautiful documentation. .. cssclass:: sphinx-tagline
.. epigraph:: Create intelligent and beautiful documentation with ease
Here are some of Sphinx's major features: .. container:: sphinx-features
* **Output formats:** HTML (including Windows HTML Help), LaTeX (for printable .. admonition:: 📝 Rich Text Formatting
PDF versions), ePub, Texinfo, manual pages, plain text :class: sphinx-feature
* **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) 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 reuse 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 Author in :ref:`reStructuredText <rst-primer>`
.. _Docutils: https://docutils.sourceforge.io/ or :ref:`MyST Markdown <markdown>`
.. _Pygments: https://pygments.org/ to create highly structured technical documents,
including tables, highlighted code blocks, mathematical notations, and more.
Sphinx uses the reStructuredText_ markup language by default, and can read .. admonition:: 🔗 Powerful Cross-Referencing
:ref:`MyST markdown <markdown>` via third-party extensions. Both of these :class: sphinx-feature
are powerful and straightforward to use, and have functionality
for complex documentation and publishing workflows. They both build upon Create :ref:`cross-references <xref-syntax>`
Docutils_ to parse and write documents. within your project,
and even across :ref:`different projects <ext-intersphinx>`.
Include references to
sections, figures, tables, citations, glossaries, code objects,
and more.
.. admonition:: 📚 Versatile Documentation Formats
:class: sphinx-feature
Generate documentation in in the preferred formats of your audience, including
HTML, LaTeX (for PDF), ePub, Texinfo, :ref:`and more <builders>`.
.. admonition:: 🎨 Extensive Theme Support
:class: sphinx-feature
Create visually appealing documentation,
with a wide choice of :ref:`built-in <builtin-themes>`
and :ref:`third-party <third-party-themes>` HTML themes
and the ability to customize
or :ref:`create new themes <extension-html-theme>`.
.. admonition:: 🔌 Fully Extensible
:class: sphinx-feature
Add custom functionality,
via robust :ref:`extension mechanisms <extending-sphinx>`
with numerous :ref:`built-in <builtin-extensions>`
and :ref:`third-party <third-party-extensions>`
extensions available for tasks like
creating diagrams, testing code, and more.
.. admonition:: 🛠️ Automatic API Documentation
:class: sphinx-feature
Generate API documentation for
Python, C++ and other :ref:`software domains <usage-domains>`,
manually or :ref:`automatically from docstrings <ext-autodoc>`,
ensuring your code documentation
stays up-to-date with minimal effort.
.. admonition:: 🌍 Internationalization (i18n)
:class: sphinx-feature
Add documentation :ref:`translations <intl>`
multiple languages to reach a global audience.
.. admonition:: 🌟 Active Community and Support
:class: sphinx-feature
Benefit from an :ref:`active community <support-index>`,
with numerous resources, tutorials, forums, and examples.
.. .. admonition:: 🌐 Integration with Version Control
.. :class: sphinx-feature
.. Sphinx integrates seamlessly with version control systems like Git.
.. This allows for easy collaboration, version tracking,
.. and deployment of documentation as part of a continuous integration pipeline.
----------------
.. container:: sphinx-users
As used by:
.. container:: sphinx-users-logos
.. figure:: _static/python-logo.png
:alt: Python Logo
:height: 100px
:align: center
:target: https://docs.python.org
Python Foundation
.. figure:: _static/linux-logo.png
:alt: Linux Logo
:height: 100px
:align: center
:target: https://docs.kernel.org/
Linux Kernel
.. figure:: _static/jupyter-logo.png
:alt: Jupyter Logo
:height: 100px
:align: center
:target: https://docs.jupyter.org
Project Jupyter
----------------
See below for how to navigate Sphinx's documentation. See below for how to navigate Sphinx's documentation.
@@ -53,10 +129,10 @@ creating and building your own documentation from scratch.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
:caption: Get started :caption: The Basics
usage/quickstart
usage/installation usage/installation
usage/quickstart
tutorial/index tutorial/index
.. _user-guides: .. _user-guides:
@@ -75,8 +151,8 @@ starting with :ref:`get-started`.
usage/index usage/index
development/index development/index
latex
extdev/index extdev/index
latex
Community guide Community guide
=============== ===============

29
doc/support.rst
View File

@@ -1,20 +1,29 @@
.. _support-index:
Get support Get support
=========== ===========
For questions or to report problems with Sphinx, join the `sphinx-users`_ For questions or to report problems with Sphinx:
mailing list on Google Groups, come to the ``#sphinx-doc`` channel on
`libera.chat`_, or open an issue at the tracker_.
- Please verify that your question does not exist on StackOverflow_
(with the tag ``python-sphinx``)
- open a topic at the `Github discussions`_ page,
- open an issue at the `Github issues`_ page,
- or join the `sphinx-users`_ mailing list on Google Groups,
.. _StackOverflow: https://stackoverflow.com/questions/tagged/python-sphinx
.. _sphinx-users: https://groups.google.com/group/sphinx-users .. _sphinx-users: https://groups.google.com/group/sphinx-users
.. _libera.chat: https://web.libera.chat/?channel=#sphinx-doc .. _Github discussions: https://github.com/sphinx-doc/sphinx/discussions
.. _tracker: https://github.com/sphinx-doc/sphinx/issues .. _Github issues: https://github.com/sphinx-doc/sphinx/issues
Examples of other projects using Sphinx can be found in the :doc:`examples page Examples of other projects using Sphinx can be found in the
<examples>`. A useful tutorial_ has been written by the matplotlib developers. :doc:`examples page <examples>`.
.. _tutorial: https://matplotlib.sourceforge.net/sampledoc/ See also the guide by ReadTheDocs_ on how to get started with Sphinx.
There is a translation team in Transifex_ of this documentation, thanks to the .. _Readthedocs: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
Sphinx document translators.
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/ .. _Transifex: https://www.transifex.com/sphinx-doc/sphinx-doc/dashboard/

5
doc/tutorial/index.rst
View File

@@ -1,8 +1,7 @@
.. _tutorial: .. _tutorial:
================================== Build your first project
Tutorial: Build your first project ========================
==================================
In this tutorial you will build a simple documentation project using Sphinx, and 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, view it in your browser as HTML. The project will include narrative,

2
doc/usage/domains/index.rst
View File

@@ -1,5 +1,7 @@
.. highlight:: rst .. highlight:: rst
.. _usage-domains:
======= =======
Domains Domains
======= =======

2
doc/usage/extensions/autodoc.rst
View File

@@ -1,5 +1,7 @@
.. highlight:: rest .. highlight:: rest
.. _ext-autodoc:
:mod:`sphinx.ext.autodoc` -- Include documentation from docstrings :mod:`sphinx.ext.autodoc` -- Include documentation from docstrings
================================================================== ==================================================================

2
doc/usage/extensions/intersphinx.rst
View File

@@ -1,3 +1,5 @@
.. _ext-intersphinx:
:mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation :mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation
====================================================================== ======================================================================

4
doc/usage/theming.rst
View File

@@ -22,7 +22,7 @@ Themes
This section provides information about using pre-existing HTML themes. If This section provides information about using pre-existing HTML themes. If
you wish to create your own theme, refer to you wish to create your own theme, refer to
:doc:`/development/theming`. :ref:`extension-html-theme`.
Sphinx supports changing the appearance of its HTML output via *themes*. A Sphinx supports changing the appearance of its HTML output via *themes*. A
theme is a collection of HTML templates, stylesheet(s) and other static files. theme is a collection of HTML templates, stylesheet(s) and other static files.
@@ -81,7 +81,7 @@ zipfile-based theme::
html_theme = "dotted" html_theme = "dotted"
For more information on the design of themes, including information about For more information on the design of themes, including information about
writing your own themes, refer to :doc:`/development/theming`. writing your own themes, refer to :ref:`extension-html-theme`.
.. _builtin-themes: .. _builtin-themes: