Skip to content

Commit 5d4cdf7

Browse files
2bndy52bndy5
authored
Backlogged doc updates (#247)
* resolves #234 * resolves #190 * resolves #242 move the pytest hardcoded options from pyproject.toml to noxfile.py adds a tests/README.rst to document the dev workflow for unit testing. * resolve #162 The MyST example doc is a bit raw, but it is meant to encourage further contributions by providing a foundation to build on.
1 parent a738925 commit 5d4cdf7

File tree

8 files changed

+668
-4
lines changed

8 files changed

+668
-4
lines changed

‎docs/conf.py‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,11 +60,13 @@
6060
"sphinx_immaterial.apidoc.cpp.apigen",
6161
"sphinx_immaterial.graphviz",
6262
"sphinx_jinja",
63+
"myst_parser",
6364
]
6465

6566
intersphinx_mapping = {
6667
"python": ("https://docs.python.org/3", None),
6768
"sphinx_docs": ("https://www.sphinx-doc.org/en/master", None),
69+
"MyST parser docs": ("https://myst-parser.readthedocs.io/en/latest", None),
6870
}
6971

7072
# The reST default role (used for this markup: `text`) to use for all
@@ -440,6 +442,28 @@
440442

441443
graphviz_ignore_incorrect_font_metrics = True
442444

445+
# MyST parser config options
446+
myst_enable_extensions = [
447+
"deflist",
448+
"fieldlist",
449+
"smartquotes",
450+
"replacements",
451+
"strikethrough",
452+
"substitution",
453+
"tasklist",
454+
"attrs_inline",
455+
"attrs_block",
456+
]
457+
458+
myst_enable_checkboxes = True
459+
myst_substitutions = {
460+
"role": "[role](#syntax/roles)",
461+
}
462+
463+
# Myst parser's strikethrough plugin seems to think that sphinx-immaterial doesn't use
464+
# HTML output (probably due to the custom translator mixin used).
465+
suppress_warnings = ["myst.strikethrough"]
466+
443467

444468
def _validate_parallel_build(app):
445469
# Verifies that all of the extensions defined by this theme support parallel
@@ -509,6 +533,10 @@ def _parse_confval_signature(
509533

510534

511535
def setup(app):
536+
from myst_parser._docs import MystLexer
537+
538+
app.add_lexer("myst", MystLexer)
539+
512540
app.add_object_type(
513541
"confval",
514542
"confval",

‎docs/customization.rst‎

Lines changed: 58 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -557,6 +557,7 @@ Configuration Options
557557
.. themeconf:: globaltoc_collapse
558558
559559
If true (the default value), TOC entries that are not ancestors of the current page are collapsed.
560+
Collapsed entries cannot be expanded.
560561
561562
.. warning::
562563
Setting this option to `False` may lead to large generated page sizes since the entire
@@ -787,6 +788,26 @@ aliases. Other required fields include ``version`` and ``title``.
787788
{"version": "1.0", "title": "1.0", "aliases": []},
788789
]
789790
791+
To redirect browsers to the latest version, add a ``index.html`` in the same directory as your
792+
project's ``versions.json`` file to be served as the domain's base URL. It should look something
793+
like the following:
794+
795+
.. code-block:: html
796+
797+
<!DOCTYPE HTML>
798+
<html lang="en">
799+
<head>
800+
<meta charset="utf-8">
801+
<meta http-equiv="refresh" content="0; url=latest/" />
802+
<link rel="canonical" href="latest/" />
803+
</head>
804+
<body>
805+
<p>If this page does not refresh automatically, then please direct your browser to
806+
<a href="latest/">our latest docs</a>.
807+
</p>
808+
</body>
809+
</html>
810+
790811
Customizing the layout
791812
======================
792813

@@ -917,7 +938,7 @@ demonstrates using Giscus_ which is Open Source and built on Github's Discussion
917938
ref.addEventListener("change", function() {
918939
var palette = __md_get("__palette")
919940
if (palette && typeof palette.color === "object") {
920-
var theme = palette.color.scheme === "slate" ? "dark" : "light" // (3)!
941+
var theme = palette.color.scheme === "slate" ? "dark" : "light" // (4)!
921942
922943
/* Instruct Giscus to change theme */
923944
var frame = document.querySelector(".giscus-frame")
@@ -940,8 +961,44 @@ demonstrates using Giscus_ which is Open Source and built on Github's Discussion
940961
themes are available, so you can change it to your liking.
941962
#. If changing the dark theme used by Giscus, then also change the dark theme name here as
942963
this takes affect when toggling between light and dark color :themeconf:`scheme`\ s.
964+
#. If changing the dark theme used by Giscus, then also change the dark theme name here as
965+
this takes affect when toggling between light and dark color :themeconf:`scheme`\ s.
943966
3. Enable comments for a certain page by adding the :themeconf:`show-comments` metadata to the document's source.
944967

968+
Version Banner
969+
--------------
970+
971+
If you're using :ref:`version_dropdown`, you might want to display a warning when the user visits
972+
any other version than the latest version. Using a partial template, you can override the
973+
``outdated`` block with the a new jinja template located in the project's documentation's
974+
``_templates/base.html``.
975+
976+
.. code-block:: jinja
977+
:caption: docs/_templates/base.html
978+
979+
{% extends "!base.html" %}
980+
981+
{% block outdated %}
982+
You're not viewing the latest version.
983+
<a href="{{ '../' ~ base_url}}">
984+
<strong>Click here to go to latest.</strong>
985+
</a>
986+
{% endblock %}
987+
988+
.. example:: Changing the color of the banner in dark scheme
989+
:collapsible:
990+
991+
Depending on the project's choices for :themeconf:`palette` colors, it might make the banner's
992+
text more legible to change the background color of the banner.
993+
994+
.. code-block:: css
995+
:caption: docs/_static/extra_style.css
996+
997+
/* only override for dark/slate scheme */
998+
[data-md-color-scheme="slate"] .md-banner--warning {
999+
background: var(--md-footer-bg-color);
1000+
}
1001+
9451002
New Blocks
9461003
**************
9471004
This theme has a few new block inherited from the mkdocs-material theme:

‎docs/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ This theme is an adaptation of the popular `mkdocs-material
1515
This theme is regularly maintained to stay up to date with the upstream
1616
`mkdocs-material <https://squidfunk.github.io/mkdocs-material/>`__ repository.
1717
The HTML templates, JavaScript, and styles from the `mkdocs-material
18-
<https://squidfunk.github.io/mkdocs-material/>`__ theme are incoroprated directly
18+
<https://squidfunk.github.io/mkdocs-material/>`__ theme are incorporated directly
1919
with mostly minor modifications.
2020

2121
Independent of the upstream mkdocs-material theme, this theme integrates with
@@ -141,3 +141,4 @@ or ``theme.conf`` for more details.
141141
rst_basics
142142
rst-cheatsheet/rst-cheatsheet
143143
additional_samples
144+
myst_typography

0 commit comments

Comments
 (0)