Fix documentation markup, add ref to sphinx-themes.org (#15)

Author: danirus

docs/source/index.rst

@@ -18,15 +18,15 @@ This documentation explains how to make use of the Nefertiti theme with Sphinx p
 Features
 ========
 
- * Responsive design, based on `Bootstrap 5.3 <https://getbootstrap.com/docs/5.3>`_.
- * Text input field to filter the table of contents.
- * Font configuration compliant with `EU's GDPR <https://gdpr.eu/>`_.
- * Different fonts can be used for different elements.
- * Light and dark color schemes, for normal text and code highlighted with Pygments styles.
- * Diverse color sets are available: blue, indigo, purple, pink, red, orange, yellow, ...
- * Optional highlighting of the project repository in the header.
- * Optional project version selector in the header.
- * Customizable footer links.
+* Responsive design, based on `Bootstrap 5.3 <https://getbootstrap.com/docs/5.3>`_.
+* Text input field to filter the table of contents.
+* Font configuration compliant with `EU's GDPR <https://gdpr.eu/>`_.
+* Different fonts can be used for different elements.
+* Light and dark color schemes, for normal text and code highlighted with Pygments styles.
+* Diverse color sets are available: blue, indigo, purple, pink, red, orange, yellow, ...
+* Optional highlighting of the project repository in the header.
+* Optional project version selector in the header.
+* Customizable footer links.
 
 Project background
 ==================

docs/source/quick-start.rst

@@ -43,12 +43,12 @@ Customize the theme
 
 The following features of Nefertiti for Sphinx can be customized:
 
- 1. Fonts.
- 2. Color set: blue, indigo, purple, pink, red, ...
- 3. Pygments styles for light and dark color schemes.
- 4. Repository name and URL to display it in the header.
- 5. Project version dropdown selector.
- 6. Footer links.
+1. Fonts.
+2. Color set: blue, indigo, purple, pink, red, ...
+3. Pygments styles for light and dark color schemes.
+4. Repository name and URL to display it in the header.
+5. Project version dropdown selector.
+6. Footer links.
 
 
 1. Fonts
@@ -58,16 +58,16 @@ There are 5 options related to font face customization and 2 options related to
 
 The font face options are:
 
- * ``sans_serif_font``: Default site font, defaults to `Nunito <https://www.fontsquirrel.com/fonts/nunito?q%5Bterm%5D=Nunito&q%5Bsearch_check%5D=Y>`_.
- * ``monospace_font``: Default monospace font, for code blocks, defaults to `Red Hat Mono <https://www.fontsquirrel.com/fonts/ubuntu-mono?q%5Bterm%5D=Ubuntu+Mono&q%5Bsearch_check%5D=Y>`_.
- * ``project_name_font``: The font for the Project's name. ``sans_serif_font`` otherwise.
- * ``documentation_font``: reStructuredText and Markdown content. ``sans_serif_font`` otherwise.
- * ``doc_headers_font``: To render documentation headers. ``documentation_font`` otherwise.
+* ``sans_serif_font``: Default site font, defaults to `Nunito <https://www.fontsquirrel.com/fonts/nunito?q%5Bterm%5D=Nunito&q%5Bsearch_check%5D=Y>`_.
+* ``monospace_font``: Default monospace font, for code blocks, defaults to `Red Hat Mono <https://www.fontsquirrel.com/fonts/ubuntu-mono?q%5Bterm%5D=Ubuntu+Mono&q%5Bsearch_check%5D=Y>`_.
+* ``project_name_font``: The font for the Project's name. ``sans_serif_font`` otherwise.
+* ``documentation_font``: reStructuredText and Markdown content. ``sans_serif_font`` otherwise.
+* ``doc_headers_font``: To render documentation headers. ``documentation_font`` otherwise.
 
 And the font size options:
 
- * ``monospace_font_size``: The CSS ``font-size`` for the ``monospace_font``. ie: ``"1rem"``.
- * ``documentation_font_size``: The CSS ``font-size`` for the ``documentation_font``. ie: ``"1.1rem"``.
+* ``monospace_font_size``: The CSS ``font-size`` for the ``monospace_font``. ie: ``"1rem"``.
+* ``documentation_font_size``: The CSS ``font-size`` for the ``documentation_font``. ie: ``"1.1rem"``.
 
 Edit your ``conf.py`` file and add or modify your ``html_theme_options`` setting with the following content. By the way, the fonts referred to in this example are part of the Nefertiti for Sphinx distribution. If you want to use other Open Source licensed fonts read the section "How to add more fonts" to include them with your project.
 
@@ -104,8 +104,8 @@ When ``style`` is not given the theme defaults to ``cyan``.
 
 Pygments_ is the package in charge of rendering code blocks. Sphinx supports two settings related with pygments:
 
- * ``pygments_style``, applied when browser's ``prefers-color-scheme`` returns **light**.
- * ``pygments_dark_style``, applied when browser's ``prefers-color-scheme`` returns **dark**.
+* ``pygments_style``, applied when browser's ``prefers-color-scheme`` returns **light**.
+* ``pygments_dark_style``, applied when browser's ``prefers-color-scheme`` returns **dark**.
 
 Nefertiti for Sphinx extends the use of these settings in a way that their styling is applied when the user selects the scheme in the light/dark dropdown, at the right side of the header.
 

docs/source/users-guide/components/admonitions.rst

@@ -6,9 +6,9 @@ Admonitions
 
 A Sphinx admonition consist of three elements:
 
- * the type of the admonition,
- * An optional title, and
- * the body, which is normally text.
+* the type of the admonition,
+* An optional title, and
+* the body, which is normally text.
 
 Sphinx supports the following types of admonitions: **attention**, **caution**, **danger**, **error**, **hint**, **important**, **note**, **tip**, **warning**.
 

docs/source/users-guide/components/footnotes.rst

@@ -7,8 +7,8 @@ Footnotes are a way to include additional information to a word or sentence with
 
 This section shows how footnotes are displayed with Nefertiti for Sphinx. To know more about the syntax to include footnotes, checkout the docs:
 
- * When using `Markdown <https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#footnotes>`_.
- * When using `reStructuredText <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes>`_.
+* When using `Markdown <https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#footnotes>`_.
+* When using `reStructuredText <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes>`_.
 
 Example footnote 1
 ******************

docs/source/users-guide/components/index.rst

@@ -5,19 +5,22 @@ Components
 
 The following pages contain examples of visual elements that can be included in Sphinx docs. The goals of this section are:
 
- * To show how these elements look like when using Nefertiti for Sphinx,
- * to help with the development of the theme itself, and
- * to serve as a reminder of how to include these elements in reStructuredText and Markdown documents.
+* To show how these elements look like when using Nefertiti for Sphinx,
+* to help with the development of the theme itself, and
+* to serve as a reminder of how to include these elements in reStructuredText and Markdown documents.
 
- .. toctree::
-    :maxdepth: 1
+.. toctree::
+   :maxdepth: 1
 
-    admonitions
-    code-blocks
-    headings
-    images
-    figures
-    lists
-    tables
-    math
-    footnotes
+   admonitions
+   code-blocks
+   headings
+   images
+   figures
+   lists
+   tables
+   math
+   footnotes
+
+
+The sphinx-themes.org project collects and tests many Sphinx themes with an extensive set of markup elements. Visit the section dedicated to `Nefertiti for Sphinx <https://sphinx-themes.org/sample-sites/sphinx-nefertiti/>`_ to see how the theme renders the testing documentation of sphinx-themes.org.

docs/source/users-guide/contributing.rst

@@ -8,9 +8,9 @@ How to contribute
 
 There are different ways to contribute:
 
- * If something is not working, or
- * if there is wrong or missing information in the documentation, or
- * if you would like to suggest an idea or improvement,
+* If something is not working, or
+* if there is wrong or missing information in the documentation, or
+* if you would like to suggest an idea or improvement,
 
 please, create an entry in the `issues page <https://github.com/danirus/sphinx-nefertiti/issues>`_ of Nefertiti's repository and explain the details.
 

docs/source/users-guide/customization/color-sets.rst

@@ -107,11 +107,11 @@ To apply custom style changes on top of Nefertiti you can create your own styles
 
 For example, if you wanted to use the color set **green** but using different colors in the header you would do the following:
 
- #. Create a new stylesheet, say a new ``custom.css`` file, inside your source ``_static`` directory with the style changes you want to apply to the header, and
- #. Update your ``conf.py`` file to change two entries:
+#. Create a new stylesheet, say a new ``custom.css`` file, inside your source ``_static`` directory with the style changes you want to apply to the header, and
+#. Update your ``conf.py`` file to change two entries:
 
-    * Set your ``html_style`` to ``["custom.css"]`` at module scope, to tell Sphinx to load the new stylesheet when building the site.
-    * Set ``"style"`` to ``"green"`` inside ``html_theme_options``.
+   + Set your ``html_style`` to ``["custom.css"]`` at module scope, to tell Sphinx to load the new stylesheet when building the site.
+   + Set ``"style"`` to ``"green"`` inside ``html_theme_options``.
 
 The next two sections implement the changes.
 
@@ -181,11 +181,11 @@ A color set is basically a complete new theme created out of the content given i
 
 To develop a new color set we need to go through the following steps:
 
- #. Create ``.scss`` files.
- #. Build the color set.
- #. Test the color set.
- #. Add the color set to the Sphinx theme.
- #. Use the color set.
+#. Create ``.scss`` files.
+#. Build the color set.
+#. Test the color set.
+#. Add the color set to the Sphinx theme.
+#. Use the color set.
 
 As an example the following sections show how to create a new color set called **django** that tries to resemble the colors used in the Django_ website.
 
@@ -277,8 +277,8 @@ If you had any other changes to apply specifically to the new ``django`` color s
 
 The ``package.json`` files offers two scripts to build style files:
 
- * ``css-compile``: to compile all the SASS files within the ``scss/`` directory.
- * ``watch-css``: to call ``css-compile`` when there are changes in the ``scss/`` directory.
+* ``css-compile``: to compile all the SASS files within the ``scss/`` directory.
+* ``watch-css``: to call ``css-compile`` when there are changes in the ``scss/`` directory.
 
 .. code-block:: shell
 

docs/source/users-guide/customization/fonts.rst

@@ -19,16 +19,16 @@ Font settings
 
 There are 5 font face customization settings that can be added to ``html_theme_options``, in your ``conf.py``:
 
- * **sans_serif_font**: It is the default global site font used for everything except code blocks and inline code samples. It defaults to `Nunito`_.
- * **monospace_font**: It is the default monospace font used for code blocks and inline code samples. It defaults to `Red Hat Mono`_.
- * **project_name_font**: It is the font used to render the project's name in the header and the footer. When not given it default to the **sans_serif_font** option.
- * **documentation_font**: It is the font used to render the actual documentation contained in reStructuredText or Markdown files. It defaults to the **sans_serif_font**.
- * **doc_headers_font**: It is the font used to render documentation headers. When not given it defaults to the **Georgia** web safe font.
+* **sans_serif_font**: It is the default global site font used for everything except code blocks and inline code samples. It defaults to `Nunito`_.
+* **monospace_font**: It is the default monospace font used for code blocks and inline code samples. It defaults to `Red Hat Mono`_.
+* **project_name_font**: It is the font used to render the project's name in the header and the footer. When not given it default to the **sans_serif_font** option.
+* **documentation_font**: It is the font used to render the actual documentation contained in reStructuredText or Markdown files. It defaults to the **sans_serif_font**.
+* **doc_headers_font**: It is the font used to render documentation headers. When not given it defaults to the **Georgia** web safe font.
 
 Additionally there are two font size settings:
 
- * **documentation_font_size**: Specifies the default font size for the documentation contained in reStructuredText or Markdown files. It defaults to ``1.0rem``, which corresponds to ``16px``.
- * **monospace_font_size**: Specifies the default font size to use with code blocks and inline code samples. It defaults to ``1.0rem``, corresponding to ``16px``.
+* **documentation_font_size**: Specifies the default font size for the documentation contained in reStructuredText or Markdown files. It defaults to ``1.0rem``, which corresponds to ``16px``.
+* **monospace_font_size**: Specifies the default font size to use with code blocks and inline code samples. It defaults to ``1.0rem``, corresponding to ``16px``.
 
 You can ignore these settings and let Nefertiti for Sphinx use the default font settings, or you can customize them.
 
@@ -37,20 +37,20 @@ Fonts bundled with Nefertiti
 
 Nefertiti for Sphinx is bundled with a group of fonts with licenses open for free distribution:
 
- * Assistant_
- * Exo_
- * Montserrat_
- * Mulish_
- * Nunito_
- * `Open Sans`_
- * `Red Hat Display`_
- * `Sofia Sans`_
- * Ubuntu_
- * Varta_
- * `Work Sans`_
- * `Fira Code`_ (monospace)
- * `Red Hat Mono`_ (monospace)
- * `Ubuntu Mono`_ (monospace)
+* Assistant_
+* Exo_
+* Montserrat_
+* Mulish_
+* Nunito_
+* `Open Sans`_
+* `Red Hat Display`_
+* `Sofia Sans`_
+* Ubuntu_
+* Varta_
+* `Work Sans`_
+* `Fira Code`_ (monospace)
+* `Red Hat Mono`_ (monospace)
+* `Ubuntu Mono`_ (monospace)
 
 Web safe fonts
 **************
@@ -59,12 +59,12 @@ You can customize the font settings to use Web safe fonts. Unlike the previous f
 
 Here is a list of font categories and their web safe fonts provided by all major web browsers:
 
- * **Sans Serif**: Helvetica, Arial, Arial Black, Verdana, Tahoma, Trebuchet MS, Gill Sans
- * **Serif**: Times New Roman, Georgia, Palatino, Baskerville
- * **Monospace**: Andale Mono, Courier, Lucida, Monaco
- * **Calligraphy**: Bradley Hand
- * **Cursive**: Brush Script MT, Comic Sans MS
- * **Fantasy**: Impact, Luminari
+* **Sans Serif**: Helvetica, Arial, Arial Black, Verdana, Tahoma, Trebuchet MS, Gill Sans
+* **Serif**: Times New Roman, Georgia, Palatino, Baskerville
+* **Monospace**: Andale Mono, Courier, Lucida, Monaco
+* **Calligraphy**: Bradley Hand
+* **Cursive**: Brush Script MT, Comic Sans MS
+* **Fantasy**: Impact, Luminari
 
 Example configuration
 *********************
@@ -92,11 +92,11 @@ Adding fonts
 
 Using a font not distributed with Nefertiti for Sphinx requires to:
 
- #. Create a directory to keep the font files.
- #. Get the font family files.
- #. Write the ``font-face`` declaration.
- #. Modify ``conf.py`` to make use of the font.
- #. Rebuild the project.
+#. Create a directory to keep the font files.
+#. Get the font family files.
+#. Write the ``font-face`` declaration.
+#. Modify ``conf.py`` to make use of the font.
+#. Rebuild the project.
 
 The following 5 sections explain in detail the steps to make the font `Noto Sans`_ available to your Sphinx project using Nefertiti for Sphinx.
 
@@ -118,8 +118,8 @@ In the source directory of your project, where you have your reStructuredText or
 
 The Noto Sans font family has 18 font files of which Nefertiti will use only 2:
 
- * ``NotoSans-Regular.ttf``
- * ``NotoSans-Bold.ttf``
+* ``NotoSans-Regular.ttf``
+* ``NotoSans-Bold.ttf``
 
 Copy these two files inside the ``fonts/noto-sans`` directory.
 
@@ -172,9 +172,9 @@ Once the previous steps have been completed the project can be built. The font f
 
 Once the project has been built, take a look at the generated ``static`` directory, it can be in:
 
- * ``build/html/_static``, or
- * ``_build/html/_static``, or
- * ``_build/html/static``, or similar.
+* ``build/html/_static``, or
+* ``_build/html/_static``, or
+* ``_build/html/static``, or similar.
 
 An ``ls`` command should show the ``fonts`` directory containing the ``noto-sans`` directory and the files you created inside.
 

docs/source/users-guide/customization/footer-links.rst

@@ -5,10 +5,10 @@ Footer links
 
 The footer of HTML pages built with Nefertiti for Sphinx is divided in 4 areas or strings, from top to bottom:
 
- * The area for the Nefertiti footer links.
- * The name of the project, provided by Sphinx ``project`` setting.
- * The copyright notice, provided by Sphinx ``copyright`` setting.
- * The powered by notice.
+* The area for the Nefertiti footer links.
+* The name of the project, provided by Sphinx ``project`` setting.
+* The copyright notice, provided by Sphinx ``copyright`` setting.
+* The powered by notice.
 
 The first and the last are theme specific and therefore they are represented by options within the ``html_theme_options`` setting.
 
@@ -17,8 +17,8 @@ Theme options
 
 The following two options can be customized in the ``html_theme_options``, in your project's ``conf.py`` file:
 
- #. ``footer_links``: Represents a list of strings and links.
- #. ``show_powered_by``: A boolean value.
+#. ``footer_links``: Represents a list of strings and links.
+#. ``show_powered_by``: A boolean value.
 
 1. ``footer_links``
 -------------------

docs/source/users-guide/customization/git-repository.rst

@@ -10,17 +10,17 @@ Theme options
 
 The two options to customize the Git repository are:
 
- #. ``repository_url``
- #. ``repository_name``
+#. ``repository_url``
+#. ``repository_name``
 
 1. ``repository_url``
 ---------------------
 
 Feed the ``repository_url`` with the HTTP URL of your repository. Using the ``git`` schema will not work:
 
- * Example to GitHub: ``https://github.com/torvalds/linux``
- * Example to GitLab: ``https://gitlab.com/inkscape/inkscape``
- * Example to GLib at GNOME's GitLab: ``https://gitlab.gnome.org/GNOME/glib``
+* Example to GitHub: ``https://github.com/torvalds/linux``
+* Example to GitLab: ``https://gitlab.com/inkscape/inkscape``
+* Example to GLib at GNOME's GitLab: ``https://gitlab.gnome.org/GNOME/glib``
 
 2. ``repository_name``
 ----------------------