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 {
width: 5%;
width: 2em;
}
.pageheader img {
@@ -39,10 +39,9 @@ body {
.pageheader h1{
color: white;
margin: 0;
font-weight: 600;
font-size: 3.5rem;
font-weight: 400;
font-size: 2em;
line-height: 1;
font-variant: small-caps;
}
div.document {
@@ -90,6 +89,7 @@ div.sphinxsidebar {
align-self: flex-start;
height: 100vh;
width: 250px;
min-width: 150px;
overflow-y: auto;
overflow-wrap: break-word;
margin: 0;
@@ -339,7 +339,7 @@ div.admonition, div.warning {
font-size: 0.9em;
margin: 1em 0 1em 0;
border: 1px solid #86989B;
border-radius: 2px;
border-radius: 3px;
background-color: #f7f7f7;
padding: 1rem;
}
@@ -356,9 +356,10 @@ div.admonition > pre, div.warning > pre {
div.admonition > p.admonition-title,
div.warning > p.admonition-title {
font-weight: bold;
background-color: #ddd;
background-color: #dddddd;
margin: -1rem -1rem 0.8rem -1rem;
padding: 0.3rem 1rem;
border-radius: 3px 3px 0 0;
}
div.important > p.admonition-title,
@@ -412,7 +413,7 @@ div.viewcode-block:target {
/* media queries */
/* Reduce padding & margins for smaller screens */
@media (max-width: 750px) {
@media (max-width: 768px) {
.sphinxsidebar {
display: none;
}
@@ -420,3 +421,46 @@ div.viewcode-block:target {
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
from __future__ import annotations
import os
import re
import time
import sphinx
from sphinx.application import Sphinx
os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1'
@@ -236,6 +236,7 @@ nitpick_ignore = {
# -- Extension interface -------------------------------------------------------
from sphinx import addnodes # NoQA: E402
from sphinx.application import Sphinx # NoQA: E402, TCH001
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)
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:
from sphinx.ext.autodoc import cut_lines
from sphinx.util.docfields import GroupedField
app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
app.connect('source-read', linkify_issues_in_changelog)
app.connect('build-finished', build_redirects)
app.add_object_type(
'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
==============================
This page contains general information about developing Sphinx extensions.
Make an extension depend on another extension
---------------------------------------------
Depend on another extension
===========================
Sometimes your extension depends on the functionality of another
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
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
def setup(app):
app.setup_extension("recommonmark")
app.setup_extension('sphinx.ext.autodoc')
.. note::

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

@@ -1,3 +1,5 @@
.. _extension-html-theme:
HTML theme development
======================
@@ -222,6 +224,11 @@ If your theme package contains two or more themes, please call
Templating
----------
.. toctree::
:hidden:
templating
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
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 @@
=========================
Writing Sphinx Extensions
=========================
.. _extending-sphinx:
Extending Sphinx
================
This guide is aimed at giving a quick introduction for those wishing to
develop their own extensions for Sphinx. Sphinx possesses significant
extensibility capabilities including the ability to hook into almost every
point of the build process. If you simply wish to use Sphinx with existing
extensions, refer to :doc:`/usage/index`. For a more detailed discussion of
the extension interface see :doc:`/extdev/index`.
develop their own extensions for Sphinx.
Sphinx possesses significant extensibility capabilities
including the ability to hook into almost every point of the build process.
If you simply wish to use Sphinx with existing extensions,
refer to :doc:`/usage/index`.
For a more detailed discussion of the extension interface see :doc:`/extdev/index`.
.. toctree::
:maxdepth: 2
overview
tutorials/index
builders
.. toctree::
:caption: Theming
:maxdepth: 2
templating
theming
howtos/index
html_themes/index

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".
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::

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

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

6
doc/extdev/index.rst
View File

@@ -1,7 +1,7 @@
.. _dev-extensions:
Sphinx Extensions API
=====================
Sphinx API
==========
Since many projects will need special features in their documentation, Sphinx
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``.
To see an example of use of these objects, refer to
:doc:`../development/tutorials/index`.
:ref:`the tutorials <extension-tutorials-index>`.
.. _build-phases:

2
doc/faq.rst
View File

@@ -30,7 +30,7 @@ How do I...
``sidebartoc`` block.
... write my own extension?
See the :doc:`/development/tutorials/index`.
See the :ref:`extension-tutorials-index`.
... convert from my existing docs using MoinMoin markup?
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
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) 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.
.. admonition:: 📝 Rich Text Formatting
:class: sphinx-feature
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Docutils: https://docutils.sourceforge.io/
.. _Pygments: https://pygments.org/
Author in :ref:`reStructuredText <rst-primer>`
or :ref:`MyST Markdown <markdown>`
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
: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.
.. admonition:: 🔗 Powerful Cross-Referencing
:class: sphinx-feature
Create :ref:`cross-references <xref-syntax>`
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.
@@ -53,10 +129,10 @@ creating and building your own documentation from scratch.
.. toctree::
:maxdepth: 2
:caption: Get started
:caption: The Basics
usage/quickstart
usage/installation
usage/quickstart
tutorial/index
.. _user-guides:
@@ -75,8 +151,8 @@ starting with :ref:`get-started`.
usage/index
development/index
latex
extdev/index
latex
Community guide
===============

29
doc/support.rst
View File

@@ -1,20 +1,29 @@
.. _support-index:
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_.
For questions or to report problems with Sphinx:
- 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
.. _libera.chat: https://web.libera.chat/?channel=#sphinx-doc
.. _tracker: https://github.com/sphinx-doc/sphinx/issues
.. _Github discussions: https://github.com/sphinx-doc/sphinx/discussions
.. _Github issues: 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.
Examples of other projects using Sphinx can be found in the
: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
Sphinx document translators.
.. _Readthedocs: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
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/

5
doc/tutorial/index.rst
View File

@@ -1,8 +1,7 @@
.. _tutorial:
==================================
Tutorial: Build your first project
==================================
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,

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

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

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

@@ -1,5 +1,7 @@
.. highlight:: rest
.. _ext-autodoc:
: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
======================================================================

4
doc/usage/theming.rst
View File

@@ -22,7 +22,7 @@ Themes
This section provides information about using pre-existing HTML themes. If
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
theme is a collection of HTML templates, stylesheet(s) and other static files.
@@ -81,7 +81,7 @@ zipfile-based theme::
html_theme = "dotted"
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: