From 3129da1b7f32dd30033407f5a8dcb688a9d1addb Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 13 Jul 2023 21:23:41 +0200 Subject: [PATCH 1/8] Add modern components from the Sphinx ecosystem - myst-parser - sphinx-design - sphinx-inline-tabs - sphinx-subfigure - sphinx-togglebutton - sphinxcontrib-mermaid --- CHANGES.rst | 3 +++ setup.py | 12 +++++++--- src/crate/theme/rtd/conf/__init__.py | 33 +++++++++++++++++++++++++++- 3 files changed, 44 insertions(+), 4 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index e75cf19eb..4ddaf33d7 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -6,6 +6,9 @@ CHANGES Unreleased ---------- +- Add modern components from the Sphinx ecosystem: myst-parser, sphinx-design, + sphinx-inline-tabs, sphinx-subfigure, sphinx-togglebutton, sphinxcontrib-mermaid. + 2023/05/15 0.27.1 ----------------- diff --git a/setup.py b/setup.py index 21c8123b2..1b37d3342 100644 --- a/setup.py +++ b/setup.py @@ -62,10 +62,16 @@ "Sphinx>=3.5,<6", "Jinja2>=3,<3.1", "docutils==0.16", - "sphinxcontrib-plantuml>=0.21,<1", - "sphinx_sitemap>=2,<3", - "sphinxext.opengraph>=0.4,<1", + "myst-parser[linkify]<2", "sphinx-copybutton>=0.3.1,<1", + "sphinx-design<1", + "sphinx-inline-tabs", + "sphinx-sitemap>=2,<3", + "sphinx-subfigure<1", + "sphinx-togglebutton<1", + "sphinxext.opengraph>=0.4,<1", + "sphinxcontrib-mermaid<1", + "sphinxcontrib-plantuml>=0.21,<1", ], python_requires=">=3.7", ) diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py index 2c0c247d5..4dfcd4ebe 100644 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/src/crate/theme/rtd/conf/__init__.py @@ -30,13 +30,25 @@ exclude_trees = ["pyenv", "tmp", "out", "parts", "clients", "eggs"] extensions = [ + "myst_parser", + "sphinx_copybutton", + "sphinx_design", + "sphinx_inline_tabs", "sphinx_sitemap", + "sphinx_subfigure", + "sphinx_togglebutton", "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.ifconfig", + "sphinx.ext.graphviz", + "sphinxcontrib.mermaid", "sphinxcontrib.plantuml", "sphinxext.opengraph", - "sphinx_copybutton", ] +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + # When not run on RTD, "html_context" is missing as a global variable if "html_context" not in globals(): html_context = {} @@ -72,6 +84,11 @@ # Can be used the query string of a resource URL for HTTP cache busting "ver": theme.get_version(), } +# https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html#fontawesome-icons +html_css_files = [ + "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css" +] + html_extra_path = ["_extra"] sitemap_filename = "site.xml" # These variables are overridden by Read The Docs @@ -135,6 +152,20 @@ linkcheck_retries = 3 linkcheck_timeout = 15 +# -- Options for MyST ------------------------------------------------- +myst_heading_anchors = 3 +myst_enable_extensions = [ + "attrs_block", + "attrs_inline", + "colon_fence", + "deflist", + "fieldlist", + "html_admonition", + "linkify", + "strikethrough", + "tasklist", +] + def setup(app): # Force the canonical URL in multiple ways # From 60a6ddf59f81c29154ffda5807fa4d7fc7935a00 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 13 Jul 2023 21:27:43 +0200 Subject: [PATCH 2/8] Demonstrate modern components from the Sphinx ecosystem - myst-parser - sphinx-design - sphinx-inline-tabs - sphinx-subfigure - sphinx-togglebutton - sphinxcontrib-mermaid --- docs/_static/mermaid-example.mmd | 63 +++++ docs/_static/myst-logo-wide.png | Bin 0 -> 13763 bytes docs/_static/myst-logo-wide.svg | 1 + docs/conf.py | 4 + docs/design-markdown.md | 238 ++++++++++++++++++ docs/design-restructuredtext.rst | 272 +++++++++++++++++++++ docs/diagrams.rst | 48 ++++ docs/index.rst | 14 +- docs/mermaid-diagrams-markdown.md | 33 +++ docs/mermaid-diagrams-restructuredtext.rst | 42 ++++ docs/myst-overview.md | 138 +++++++++++ 11 files changed, 852 insertions(+), 1 deletion(-) create mode 100644 docs/_static/mermaid-example.mmd create mode 100644 docs/_static/myst-logo-wide.png create mode 100644 docs/_static/myst-logo-wide.svg create mode 100644 docs/design-markdown.md create mode 100644 docs/design-restructuredtext.rst create mode 100644 docs/mermaid-diagrams-markdown.md create mode 100644 docs/mermaid-diagrams-restructuredtext.rst create mode 100644 docs/myst-overview.md diff --git a/docs/_static/mermaid-example.mmd b/docs/_static/mermaid-example.mmd new file mode 100644 index 000000000..3b13941e0 --- /dev/null +++ b/docs/_static/mermaid-example.mmd @@ -0,0 +1,63 @@ +flowchart LR + + subgraph sensors + + subgraph ism + RF-1[RF sensor 1] + RF-2[RF sensor 2] + RF-N[RF sensor N] + relay{{telemetry relay}} + end + subgraph sub1ghz + LORAWAN[LoRaWAN sensor] + LORA[LoRa sensor] + end + subgraph cellular + CELL-GSM[GSM sensor] + CELL-LTE[LTE M1/NB1 sensor] + end + + gateway{{network gateway}} + + RF-1 --> relay + RF-2 --> relay + RF-N --> relay + relay --> gateway + + TTN{TTN} + + end + + subgraph network + HTTP{HTTP} + MQTT{MQTT} + end + + subgraph backend + + Kotori>Kotori message router\nand data historian] + InfluxDB[(InfluxDB)] + CrateDB[(CrateDB)] + + Kotori --> InfluxDB + Kotori --> CrateDB + Kotori --> Grafana + + end + + %% Breadboard + + %% Sensors + LORAWAN --> TTN + LORA --> gateway + + %% Network + gateway --> network + TTN --> network + + CELL-GSM --> network + CELL-LTE --> network + + %% Kotori + MQTT --> Kotori + HTTP --> Kotori diff --git a/docs/_static/myst-logo-wide.png b/docs/_static/myst-logo-wide.png new file mode 100644 index 0000000000000000000000000000000000000000..ca6a021b2f34c19b580062df486748582f1b2a57 GIT binary patch literal 13763 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 1 diff --git a/docs/conf.py b/docs/conf.py index 0bb072789..0d39af5d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,3 +20,7 @@ html_context_custom.update({ #"display_github": False, }) + + +intersphinx_mapping["design"] = ("https://sphinx-design.readthedocs.io/en/latest/", None) +intersphinx_mapping["myst"] = ("https://myst-parser.readthedocs.io/en/latest/", None) diff --git a/docs/design-markdown.md b/docs/design-markdown.md new file mode 100644 index 000000000..18a03c47d --- /dev/null +++ b/docs/design-markdown.md @@ -0,0 +1,238 @@ +(design-elements-markdown)= +# Design elements: Markdown + +## Grid layout, cards, badges + +### Documentation +- [sphinx{design} » Grids](inv:design#sd-grids) +- [sphinx{design} » Cards](inv:design#sd-cards) +- [sphinx{design} » Badges](inv:design#badges) + +### Examples + +A composite component offering a title, description text, and both verbose and short tags. +It is suitable for authoring pages enumerating items with dense information, without +the maintenance nightmares of tables. + +:::::::{grid} 1 +:margin: 0 +:padding: 0 + +::::::{grid-item-card} +:::::{grid} 2 +:margin: 0 +:padding: 0 + +::::{grid-item} +:columns: 8 +[multihop-firmware](https://hiveeyes.org/docs/arduino/firmware/backdoor/multihop/README.html) + +A flexible software breadboard for ISM RF packet radio nodes, relays, and gateways. + +**Date:** 2015 +**Source:** multihop.ino +:::: + +::::{grid-item} +:columns: 4 +{bdg-primary-line}`rf69` {bdg-primary-line}`rf96` {bdg-primary-line}`lora` {bdg-primary-line}`beradio` + +{bdg-success-line}`hx711` {bdg-success-line}`ds18b20` {bdg-success-line}`dht22` + +{bdg-secondary-line}`ATmega328` + +{bdg-info-line}`low-power` +:::: + +::::: +:::::: +::::::: + + +## sphinx{design} Tabs + +For basic "tabs" needs. + +### Documentation +- [sphinx{design} » Tabs](inv:design#sd-tabs) + +### Examples + +::::{tab-set} + +:::{tab-item} Label1 +Content 1 +::: + +:::{tab-item} Label2 +Content 2 +::: + +:::: + + +## sphinx-inline-tabs + +For more advanced "tabs" needs. + +### Documentation + +https://sphinx-inline-tabs.readthedocs.io/ + +### Examples + +#### Basics +```{tab} Label1 +Content 1 +``` + +```{tab} Label2 +Content 2 +``` + +#### Code tabs +````{tab} Python +```python +print("Hello World!") +``` + +It's pretty simple! +```` + +````{tab} C++ +```cpp +#include + +int main() { + std::cout << "Hello World!" << std::endl; +} +``` + +More code, but it works too! +```` + +````{tab} Text +```none +Hello World! +``` + +Why not. +```` + +#### Synchronized +````{tab} Windows +```console +$ py -m pip install sphinx +``` +```` + +````{tab} Unix (MacOS / Linux) +```console +$ python -m pip install sphinx +``` +```` + +````{tab} Windows +:new-set: +```console +$ make.bat html +``` +```` + +````{tab} Unix (MacOS / Linux) +```console +$ make html +``` +```` + + +#### Nested +````{tab} Windows +```{tab} Command prompt +`cmd.exe` +``` +```{tab} Powershell +`ps2.exe` +``` +```` + +````{tab} Unix (MacOS / Linux) + +As can be seen on the other tab, the tab sets will "join" when there's +no text between different levels of tabs. Adding text between them +will space them out. + +```{tab} Bash +`bash` +``` +```{tab} Zsh +`zsh` +``` +```{tab} Fish +`fish` +``` +```{tab} Powershell +`ps2` +``` +```` + + +## Buttons + +### Documentation +- [sphinx{design} » Buttons](inv:design#buttons) + +### Examples +```{button-link} https://example.com +:color: primary +:shadow: +``` + +```{button-link} https://example.com +:color: primary +:outline: +``` + +```{button-link} https://example.com +:color: secondary +:expand: +``` + + +## Icons + +### Documentation +- [sphinx{design} » Icons](inv:design#icons) + +### Examples + +#### Octicon Icons + +A coloured icon: {octicon}`report;1em;sd-text-info`, some more text. + +- Alert: {octicon}`alert` +- Mention: {octicon}`mention` + +#### Material Design Icons + +- regular icon: {material-regular}`data_exploration;2em`, some more text +- A coloured regular icon: {material-regular}`settings;3em;sd-text-success`, some more text. +- A coloured outline icon: {material-outlined}`settings;3em;sd-text-success`, some more text. +- A coloured sharp icon: {material-sharp}`settings;3em;sd-text-success`, some more text. +- A coloured round icon: {material-round}`settings;3em;sd-text-success`, some more text. +- A coloured two-tone icon: {material-twotone}`settings;3em;sd-text-success`, some more text. +- A fixed size icon: {material-regular}`data_exploration;24px`, some more text. + +#### FontAwesome Icons + +- An icon {fas}`spinner;sd-text-primary`, some more text. +- An icon {fab}`github`, some more text. +- An icon {fab}`gitkraken;sd-text-success fa-xl`, some more text. +- An icon {fas}`skull;sd-text-danger`, some more text. + + +## Todo items + +```{todo} +Foo bar baz. +``` diff --git a/docs/design-restructuredtext.rst b/docs/design-restructuredtext.rst new file mode 100644 index 000000000..10d6e7eb7 --- /dev/null +++ b/docs/design-restructuredtext.rst @@ -0,0 +1,272 @@ +.. _design-elements-restructuredtext: + +################################# +Design elements: reStructuredText +################################# + + +************************** +Grid layout, cards, badges +************************** + +Documentation +============= + +- :ref:`sphinx{design} » Grids ` +- :ref:`sphinx{design} » Cards ` +- :ref:`sphinx{design} » Badges ` + +Examples +======== +A composite component offering a title, description text, and both verbose and short tags. +It is suitable for authoring pages enumerating items with dense information, without +the maintenance nightmares of tables. + +.. grid:: 1 + :margin: 0 + :padding: 0 + + .. grid-item-card:: + + .. grid:: 2 + :margin: 0 + :padding: 0 + + .. grid-item:: + :columns: 8 + + `multihop-firmware `_ + + A flexible software breadboard for ISM RF packet radio nodes, relays, and gateways. + + **Date:** 2015 + **Source:** multihop.ino + + .. grid-item:: + :columns: 4 + + :bdg-primary-line:`rf69` :bdg-primary-line:`rf96` :bdg-primary-line:`lora` :bdg-primary-line:`beradio` + + :bdg-success-line:`hx711` :bdg-success-line:`ds18b20` :bdg-success-line:`dht22` + + :bdg-secondary-line:`ATmega328` + + :bdg-info-line:`low-power` + + + +******************* +sphinx{design} Tabs +******************* + +For basic "tabs" needs. + +Documentation +============= +- :ref:`sphinx{design} » Tabs ` + +Examples +======== + +.. tab-set:: + + .. tab-item:: Label1 + + Content 1 + + .. tab-item:: Label2 + + Content 2 + + +****************** +sphinx-inline-tabs +****************** + +For more advanced "tabs" needs. + +Documentation +============= + +https://sphinx-inline-tabs.readthedocs.io/ + +Examples +======== + +Basics +------ + +.. tab:: Label1 + + Content 1 + +.. tab:: Label2 + + Content 2 + +Code tabs +--------- + +.. tab:: Python + + .. code-block:: python + + print("Hello World!") + + It's pretty simple! + +.. tab:: C++ + + .. code-block:: cpp + + #include + + int main() { + std::cout << "Hello World!" << std::endl; + + } + + More code, but it works too! + +.. tab:: Text + + .. code-block:: none + + Hello World! + + Why not. + +Synchronized +------------ + +.. tab:: Windows + + .. code-block:: console + + $ py -m pip install sphinx + +.. tab:: Unix (MacOS / Linux) + + .. code-block:: console + + $ python -m pip install sphinx + + +.. tab:: Windows + :new-set: + + .. code-block:: console + + $ make.bat html + +.. tab:: Unix (MacOS / Linux) + + .. code-block:: console + + $ make html + +Nested +------ + +.. tab:: Windows + + .. tab:: Command prompt + + ``cmd.exe`` + + .. tab:: Powershell + + ``ps2.exe`` + + +.. tab:: Unix (MacOS / Linux) + + As can be seen on the other tab, the tab sets will "join" when there's + no text between different levels of tabs. Adding text between them + will space them out. + + .. tab:: Bash + + ``bash`` + + .. tab:: Zsh + + ``zsh`` + + .. tab:: Fish + + ``fish`` + + .. tab:: Powershell + + ``ps2`` + + +******* +Buttons +******* + +Documentation +============= +- :ref:`sphinx{design} » Buttons ` + +Examples +======== +.. button-link:: https://example.com + :color: primary + :shadow: + +.. button-link:: https://example.com + :color: primary + :outline: + +.. button-link:: https://example.com + :color: secondary + :expand: + + + +***** +Icons +***** + +Documentation +============= +- :ref:`sphinx{design} » Icons ` + +Examples +======== + +Octicon Icons +------------- + +A coloured icon: :octicon:`report;1em;sd-text-info`, some more text. + +- Alert: :octicon:`alert` +- Mention: :octicon:`mention` + +Material Design Icons +--------------------- + +- regular icon: :material-regular:`data_exploration;2em`, some more text +- A coloured regular icon: :material-regular:`settings;3em;sd-text-success`, some more text. +- A coloured outline icon: :material-outlined:`settings;3em;sd-text-success`, some more text. +- A coloured sharp icon: :material-sharp:`settings;3em;sd-text-success`, some more text. +- A coloured round icon: :material-round:`settings;3em;sd-text-success`, some more text. +- A coloured two-tone icon: :material-twotone:`settings;3em;sd-text-success`, some more text. +- A fixed size icon: :material-regular:`data_exploration;24px`, some more text. + +FontAwesome Icons +----------------- + +- An icon :fas:`spinner;sd-text-primary`, some more text. +- An icon :fab:`github`, some more text. +- An icon :fab:`gitkraken;sd-text-success fa-xl`, some more text. +- An icon :fas:`skull;sd-text-danger`, some more text. + + +Todo items +========== +.. todo:: + + Foo bar baz. diff --git a/docs/diagrams.rst b/docs/diagrams.rst index 6be6ba2ad..67a5801fe 100644 --- a/docs/diagrams.rst +++ b/docs/diagrams.rst @@ -9,3 +9,51 @@ PlantUML Alice -> Bob: Hi! Alice <- Bob: How are you? + +Mermaid +======= + +.. mermaid:: + + flowchart LR + + subgraph sensors + + subgraph ism + RF-1[RF sensor 1] + RF-2[RF sensor 2] + RF-N[RF sensor N] + relay{{telemetry relay}} + end + subgraph sub1ghz + LORAWAN[LoRaWAN sensor] + LORA[LoRa sensor] + end + subgraph cellular + CELL-GSM[GSM sensor] + CELL-LTE[LTE M1/NB1 sensor] + end + + gateway{{network gateway}} + + RF-1 --> relay + RF-2 --> relay + RF-N --> relay + relay --> gateway + + TTN{TTN} + + end + + %% Breadboard + + %% Sensors + LORAWAN --> TTN + LORA --> gateway + + %% Network + gateway --> network + TTN --> network + + CELL-GSM --> network + CELL-LTE --> network diff --git a/docs/index.rst b/docs/index.rst index 9108b7316..6bade34b7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,6 +39,7 @@ How to improve this documentation: .. toctree:: :maxdepth: 1 + :caption: Classic Sphinx / reStructuredText headings admonitions @@ -48,10 +49,21 @@ How to improve this documentation: images diagrams codesnippets - subpage glossary +.. toctree:: + :maxdepth: 1 + :caption: Modern components + + myst-overview + design-markdown + design-restructuredtext + mermaid-diagrams-markdown + mermaid-diagrams-restructuredtext + + + .. _developer guide: https://github.com/crate/crate-docs-theme/blob/main/DEVELOP.rst .. _report an issue: https://github.com/crate/crate-docs-theme/issues/new diff --git a/docs/mermaid-diagrams-markdown.md b/docs/mermaid-diagrams-markdown.md new file mode 100644 index 000000000..075478da7 --- /dev/null +++ b/docs/mermaid-diagrams-markdown.md @@ -0,0 +1,33 @@ +# Mermaid diagrams: Markdown + + +## About + +[Mermaid] is a JavaScript based diagramming and charting tool that renders Markdown- +inspired text definitions to create and modify diagrams dynamically. + +By adding a `mermaid` directive, the [sphinxcontrib-mermaid] extension allows you to +embed Mermaid graphs in your documents, including general flowcharts, sequence diagrams, +gantt diagrams, and more. + +The most popular chart will probably be a flowchart, see [Flowcharts - Basic Syntax] +for an introduction. + +[Mermaid]: https://mermaid.js.org/ +[Flowcharts - Basic Syntax]: https://mermaid.js.org/syntax/flowchart.html +[sphinxcontrib-mermaid]: https://pypi.org/project/sphinxcontrib-mermaid/ + + +## Examples + +### Sequence diagram +```{mermaid} +sequenceDiagram + participant Alice + participant Bob + Alice->John: Hello John, how are you? +``` + +### Flowchart diagram +```{mermaid} _static/mermaid-example.mmd +``` diff --git a/docs/mermaid-diagrams-restructuredtext.rst b/docs/mermaid-diagrams-restructuredtext.rst new file mode 100644 index 000000000..903462958 --- /dev/null +++ b/docs/mermaid-diagrams-restructuredtext.rst @@ -0,0 +1,42 @@ +################################## +Mermaid diagrams: reStructuredText +################################## + + +***** +About +***** + +`Mermaid`_ is a JavaScript based diagramming and charting tool that renders Markdown- +inspired text definitions to create and modify diagrams dynamically. + +By adding a ``mermaid`` directive, the `sphinxcontrib-mermaid`_ extension allows you to +embed Mermaid graphs in your documents, including general flowcharts, sequence diagrams, +gantt diagrams, and more. + +The most popular chart will probably be a flowchart, see `Flowcharts - Basic Syntax`_ +for an introduction. + +.. _Mermaid: https://mermaid.js.org/ +.. _Flowcharts - Basic Syntax: https://mermaid.js.org/syntax/flowchart.html +.. _sphinxcontrib-mermaid: https://pypi.org/project/sphinxcontrib-mermaid/ + + +******** +Examples +******** + +Sequence diagram +================ + +.. mermaid:: + + sequenceDiagram + participant Alice + participant Bob + Alice->John: Hello John, how are you? + +Flowchart diagram +================= + +.. mermaid:: _static/mermaid-example.mmd diff --git a/docs/myst-overview.md b/docs/myst-overview.md new file mode 100644 index 000000000..50882cc80 --- /dev/null +++ b/docs/myst-overview.md @@ -0,0 +1,138 @@ +# Overview about MyST - Markedly Structured Text + +## About + +> A Sphinx and Docutils extension to parse MyST, a rich and extensible flavour +> of Markdown for authoring technical and scientific documentation. +> +> -- https://myst-parser.readthedocs.io/ + +## Details + +### The great dilemma + +For a long time, the power of the Sphinx documentation generator was only available +to people writing documentation in reStructuredText. Because Markdown gained +significant popularity in recent years, the community was in a big dilemma, and I +am sure there have been endless Programming Language Wars-style discussions about +using reStructuredText vs. Markdown for documentation authoring. + +This dilemma has come to an end with MyST now, aiming to follow up on the success +of MySQL and mypy – naming-wise. + + +### Enter MyST + +[MyST](https://myst-parser.readthedocs.io/) is a strict superset of the +[CommonMark syntax specification](https://spec.commonmark.org/). +It adds features focussed on scientific and technical documentation authoring. + +Effectively, it brings Markdown to Sphinx in full swing – finally. {fas}`star2` + +Roles and directives provide a way to extend the syntax of MyST in an unbound +manner, by interpreting a chunk of text as a specific type of markup, according +to its name. +Directives syntax is defined with triple-backticks and curly-brackets, effectively +a Markdown code fence. + +-– [Roles and Directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html) + +#### Example + +> ![image|297x168](https://global.discourse-cdn.com/business7/uploads/crate/original/1X/d61bae27e7ce2ca04ab7ba78954153b885f2548e.png) + + +## Inline quotes / citations + +> This text should be quoted. + +## Cross-references + +Being able to use cross-references appropriately, i.e. optimally linking between +documentation resources, even across projects, is important for documentation +authoring. Please refer to [MyST cross-references], in order to learn about how +this works using the Markdown markup language. + +By using cross-references properly, maintenance efforts regarding broken links will +be greatly reduced, because all target references will be validated at build time. +See also [How to use cross-references with Sphinx]. + + +## Images and figures + +### Documentation +- [sphinx{design} » Images and figures](inv:myst#syntax/images_and_figures) +- {doc}`sphinx{design} » Images and figures ` + +### Standard + +The standard Markdown syntax for images. + +![MyST logo](_static/myst-logo-wide.svg) + +### Adjusting attributes +The `attrs_inline` extension can be used to add attributes to an inline image, +for example, to resize/scale it. + +![MyST logo](_static/myst-logo-wide.svg){.bg-warning w=100px align=center} + +### Block level +To create a block image, use the `image` directive. +```{image} https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg +:alt: fishy +:class: bg-primary +:width: 200px +:align: center +``` + + +### Figures (images with captions) + +To create a figure, use the `figure` directive. + +```{figure} _static/myst-logo-wide.png +:scale: 50 % +:alt: The MyST logo. + +This is the caption of the figure (a simple paragraph). + +The legend consists of all elements after the caption. In this +case, the legend consists of this paragraph and the following +table: + +| Symbol | Meaning | +| ------ | ------- | +| :logo: | MyST | +``` + + +### Subfigures + +Documentation: https://sphinx-subfigure.readthedocs.io/ + +:::{subfigure} AA|BC +:layout-sm: A|B|C +:gap: 8px +:subcaptions: above +:name: myfigure +:class-grid: outline + +```{image} https://sphinx-subfigure.readthedocs.io/en/latest/_images/A.png +:height: 100px +:alt: Image A +``` + +```{image} https://sphinx-subfigure.readthedocs.io/en/latest/_images/B.png +:height: 100px +:alt: Image B +``` + +```{image} https://sphinx-subfigure.readthedocs.io/en/latest/_images/C.png +:height: 100px +:alt: Image C +``` + + +[How to use cross-references with Sphinx]: https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html +[MyST cross-references]: inv:myst#syntax/referencing +[myst-logo]: https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg From 812610e4ff51d11dbcb5a8ecc86583c8d2fd4c5b Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 13 Jul 2023 23:28:15 +0200 Subject: [PATCH 3/8] Documentation: Improve index page --- docs/index.rst | 82 +++++++++++++++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 31 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 6bade34b7..59eb2efb8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,45 +1,31 @@ .. _index: -========== -Page Title -========== +########################### +CrateDB documentation theme +########################### -.. meta:: - :description lang=en: - This is the meta description, it should be between 150-300 characters. - Meta descriptions are used for display but not for ranking. +***** +About +***** -This is a sample documentation project that can be used for visually testing -the theme. +A theme component for the `Sphinx static documentation generator`_. -How to use this documentation: +Example documentation sections: -- Verify that each page element displays correctly. Some page elements identify - themselves (e.g., the :ref:`index`) and some elements describe how they ought - to appear (e.g., the :ref:`first admonition `). +- https://crate.io/docs/crate/reference/ +- https://crate.io/docs/python/en/latest/ -How to improve this documentation: +******** +Overview +******** -- If you notice any bugs, please `report an issue`_ or create a PR to fix them. - -- Add page elements and use the available text to describe how the element - should be displayed. - - -.. NOTE:: - - For help building this documentation as a part of your testing and *Quality - Assurance* (QA) workflow, see the `developer guide`_. - -.. rubric:: Table of Contents - -.. contents:: - :local: +This section outlines a few features, elements, and style-guides by example. +Classic Sphinx / reStructuredText +================================= .. toctree:: :maxdepth: 1 - :caption: Classic Sphinx / reStructuredText headings admonitions @@ -53,9 +39,11 @@ How to improve this documentation: glossary +Modern components +================= + .. toctree:: :maxdepth: 1 - :caption: Modern components myst-overview design-markdown @@ -64,6 +52,38 @@ How to improve this documentation: mermaid-diagrams-restructuredtext +******* +Details +******* + +.. meta:: + :description lang=en: + This is the meta description, it should be between 150-300 characters. + Meta descriptions are used for display but not for ranking. + +This is a sample documentation project that can be used for visually testing +the theme. + +How to use this documentation: + +- Verify that each page element displays correctly. Some page elements identify + themselves (e.g., the :ref:`index`) and some elements describe how they ought + to appear (e.g., the :ref:`first admonition `). + +How to improve this documentation: + +- If you notice any bugs, please `report an issue`_ or create a PR to fix them. + +- Add page elements and use the available text to describe how the element + should be displayed. + + +.. NOTE:: + + To learn how to run sandbox or CI builds as a part of your testing and *Quality + Assurance* (QA) workflow, see the `developer guide`_. + .. _developer guide: https://github.com/crate/crate-docs-theme/blob/main/DEVELOP.rst .. _report an issue: https://github.com/crate/crate-docs-theme/issues/new +.. _Sphinx static documentation generator: https://www.sphinx-doc.org/ From 575f4cc4ad2b80c5db156a485436b19206da6ec6 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Fri, 14 Jul 2023 10:56:54 +0200 Subject: [PATCH 4/8] Documentation: Improve MyST overview page --- docs/myst-overview.md | 62 +++++++++++++++++++++---------------------- 1 file changed, 30 insertions(+), 32 deletions(-) diff --git a/docs/myst-overview.md b/docs/myst-overview.md index 50882cc80..8d28d3836 100644 --- a/docs/myst-overview.md +++ b/docs/myst-overview.md @@ -7,27 +7,12 @@ > > -- https://myst-parser.readthedocs.io/ -## Details - -### The great dilemma - -For a long time, the power of the Sphinx documentation generator was only available -to people writing documentation in reStructuredText. Because Markdown gained -significant popularity in recent years, the community was in a big dilemma, and I -am sure there have been endless Programming Language Wars-style discussions about -using reStructuredText vs. Markdown for documentation authoring. - -This dilemma has come to an end with MyST now, aiming to follow up on the success -of MySQL and mypy – naming-wise. - - -### Enter MyST - [MyST](https://myst-parser.readthedocs.io/) is a strict superset of the [CommonMark syntax specification](https://spec.commonmark.org/). -It adds features focussed on scientific and technical documentation authoring. +It adds features focussed on scientific and technical documentation authoring. {fas}`star2` + -Effectively, it brings Markdown to Sphinx in full swing – finally. {fas}`star2` +### Details Roles and directives provide a way to extend the syntax of MyST in an unbound manner, by interpreting a chunk of text as a specific type of markup, according @@ -37,46 +22,50 @@ a Markdown code fence. -– [Roles and Directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html) -#### Example +**Example** > ![image|297x168](https://global.discourse-cdn.com/business7/uploads/crate/original/1X/d61bae27e7ce2ca04ab7ba78954153b885f2548e.png) -## Inline quotes / citations +## Overview + +### Inline quotes / citations > This text should be quoted. -## Cross-references +### Cross-references Being able to use cross-references appropriately, i.e. optimally linking between documentation resources, even across projects, is important for documentation -authoring. Please refer to [MyST cross-references], in order to learn about how -this works using the Markdown markup language. +authoring. Please refer to [MyST cross-references](inv:myst#syntax/referencing), +in order to learn about how this works using the Markdown markup language. By using cross-references properly, maintenance efforts regarding broken links will be greatly reduced, because all target references will be validated at build time. See also [How to use cross-references with Sphinx]. +[How to use cross-references with Sphinx]: https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html + -## Images and figures +### Images and figures -### Documentation +#### Documentation - [sphinx{design} » Images and figures](inv:myst#syntax/images_and_figures) - {doc}`sphinx{design} » Images and figures ` -### Standard +#### Standard The standard Markdown syntax for images. ![MyST logo](_static/myst-logo-wide.svg) -### Adjusting attributes +#### Adjusting attributes The `attrs_inline` extension can be used to add attributes to an inline image, for example, to resize/scale it. ![MyST logo](_static/myst-logo-wide.svg){.bg-warning w=100px align=center} -### Block level +#### Block level To create a block image, use the `image` directive. ```{image} https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg :alt: fishy @@ -86,7 +75,7 @@ To create a block image, use the `image` directive. ``` -### Figures (images with captions) +#### Figures (images with captions) To create a figure, use the `figure` directive. @@ -132,7 +121,16 @@ Documentation: https://sphinx-subfigure.readthedocs.io/ :alt: Image C ``` +::: -[How to use cross-references with Sphinx]: https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html -[MyST cross-references]: inv:myst#syntax/referencing -[myst-logo]: https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg + +## History - The great dilemma + +For a long time, the power of the Sphinx documentation generator was only available +to people writing documentation in reStructuredText. Because Markdown gained +significant popularity in recent years, the community was in a big dilemma, and +surely there have been endless Programming Language Wars-style discussions about +using reStructuredText vs. Markdown for documentation authoring. + +This dilemma has come to an end with MyST now, aiming to follow up on the success +of MySQL and mypy – naming-wise. From 86d85918f832d33d415c0b823db628be3cd322ee Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 20 Jul 2023 00:41:14 +0200 Subject: [PATCH 5/8] Dependencies: Use `sphinx-design-elements` --- setup.py | 1 + src/crate/theme/rtd/conf/__init__.py | 1 + 2 files changed, 2 insertions(+) diff --git a/setup.py b/setup.py index 1b37d3342..255101613 100644 --- a/setup.py +++ b/setup.py @@ -65,6 +65,7 @@ "myst-parser[linkify]<2", "sphinx-copybutton>=0.3.1,<1", "sphinx-design<1", + "sphinx-design-elements==0.1.0", "sphinx-inline-tabs", "sphinx-sitemap>=2,<3", "sphinx-subfigure<1", diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py index 4dfcd4ebe..80059dc03 100644 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/src/crate/theme/rtd/conf/__init__.py @@ -33,6 +33,7 @@ "myst_parser", "sphinx_copybutton", "sphinx_design", + "sphinx_design_elements", "sphinx_inline_tabs", "sphinx_sitemap", "sphinx_subfigure", From 43d53426450923e9fa0e08c1178fc80b201544a4 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 20 Jul 2023 00:41:24 +0200 Subject: [PATCH 6/8] Dependencies: This and that --- setup.py | 1 + src/crate/theme/rtd/conf/__init__.py | 3 +++ 2 files changed, 4 insertions(+) diff --git a/setup.py b/setup.py index 255101613..e34b438ca 100644 --- a/setup.py +++ b/setup.py @@ -62,6 +62,7 @@ "Sphinx>=3.5,<6", "Jinja2>=3,<3.1", "docutils==0.16", + "docutils-stubs==0.0.22", "myst-parser[linkify]<2", "sphinx-copybutton>=0.3.1,<1", "sphinx-design<1", diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py index 80059dc03..de43e338e 100644 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/src/crate/theme/rtd/conf/__init__.py @@ -162,8 +162,11 @@ "deflist", "fieldlist", "html_admonition", + "html_image", "linkify", + "replacements", "strikethrough", + "substitution", "tasklist", ] From a2ceb1ecfc9040d298564ee1d721ce03703daa6b Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 20 Jul 2023 00:42:13 +0200 Subject: [PATCH 7/8] Documentation: Refactor into legacy vs. modernized sections - The legacy feature gallery exclusively uses reStructuredText. - The modernized feature gallery demonstrates both reStructuredText and Markedly Structured Text syntax. --- docs/conf.py | 3 +- docs/design-markdown.md | 238 --------------- docs/design-restructuredtext.rst | 272 ------------------ docs/index.rst | 55 ++-- docs/myst-overview.md | 136 --------- docs/myst/button.md | 20 ++ docs/myst/crossref.md | 12 + docs/myst/icon.md | 30 ++ docs/myst/image-figure.md | 75 +++++ docs/myst/index.md | 10 + docs/myst/infocard.md | 99 +++++++ docs/myst/introduction.md | 40 +++ .../mermaid.md} | 4 +- docs/myst/misc.md | 13 + docs/myst/sphinx-design.md | 9 + docs/myst/tab.md | 128 +++++++++ docs/myst/table.md | 65 +++++ docs/rst/button.rst | 21 ++ docs/rst/icon.rst | 37 +++ docs/rst/index.rst | 11 + docs/rst/infocard.rst | 100 +++++++ docs/rst/introduction.rst | 21 ++ .../mermaid.rst} | 8 +- docs/rst/misc.rst | 14 + docs/rst/sphinx-design.rst | 17 ++ docs/rst/tab.rst | 150 ++++++++++ docs/rst/table.rst | 50 ++++ 27 files changed, 967 insertions(+), 671 deletions(-) delete mode 100644 docs/design-markdown.md delete mode 100644 docs/design-restructuredtext.rst delete mode 100644 docs/myst-overview.md create mode 100644 docs/myst/button.md create mode 100644 docs/myst/crossref.md create mode 100644 docs/myst/icon.md create mode 100644 docs/myst/image-figure.md create mode 100644 docs/myst/index.md create mode 100644 docs/myst/infocard.md create mode 100644 docs/myst/introduction.md rename docs/{mermaid-diagrams-markdown.md => myst/mermaid.md} (92%) create mode 100644 docs/myst/misc.md create mode 100644 docs/myst/sphinx-design.md create mode 100644 docs/myst/tab.md create mode 100644 docs/myst/table.md create mode 100644 docs/rst/button.rst create mode 100644 docs/rst/icon.rst create mode 100644 docs/rst/index.rst create mode 100644 docs/rst/infocard.rst create mode 100644 docs/rst/introduction.rst rename docs/{mermaid-diagrams-restructuredtext.rst => rst/mermaid.rst} (86%) create mode 100644 docs/rst/misc.rst create mode 100644 docs/rst/sphinx-design.rst create mode 100644 docs/rst/tab.rst create mode 100644 docs/rst/table.rst diff --git a/docs/conf.py b/docs/conf.py index 0d39af5d7..45cfc092a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,5 +22,6 @@ }) -intersphinx_mapping["design"] = ("https://sphinx-design.readthedocs.io/en/latest/", None) intersphinx_mapping["myst"] = ("https://myst-parser.readthedocs.io/en/latest/", None) +intersphinx_mapping["sd"] = ("https://sphinx-design.readthedocs.io/en/latest/", None) +intersphinx_mapping["sde"] = ("https://sphinx-design-elements.readthedocs.io/en/latest/", None) diff --git a/docs/design-markdown.md b/docs/design-markdown.md deleted file mode 100644 index 18a03c47d..000000000 --- a/docs/design-markdown.md +++ /dev/null @@ -1,238 +0,0 @@ -(design-elements-markdown)= -# Design elements: Markdown - -## Grid layout, cards, badges - -### Documentation -- [sphinx{design} » Grids](inv:design#sd-grids) -- [sphinx{design} » Cards](inv:design#sd-cards) -- [sphinx{design} » Badges](inv:design#badges) - -### Examples - -A composite component offering a title, description text, and both verbose and short tags. -It is suitable for authoring pages enumerating items with dense information, without -the maintenance nightmares of tables. - -:::::::{grid} 1 -:margin: 0 -:padding: 0 - -::::::{grid-item-card} -:::::{grid} 2 -:margin: 0 -:padding: 0 - -::::{grid-item} -:columns: 8 -[multihop-firmware](https://hiveeyes.org/docs/arduino/firmware/backdoor/multihop/README.html) - -A flexible software breadboard for ISM RF packet radio nodes, relays, and gateways. - -**Date:** 2015 -**Source:** multihop.ino -:::: - -::::{grid-item} -:columns: 4 -{bdg-primary-line}`rf69` {bdg-primary-line}`rf96` {bdg-primary-line}`lora` {bdg-primary-line}`beradio` - -{bdg-success-line}`hx711` {bdg-success-line}`ds18b20` {bdg-success-line}`dht22` - -{bdg-secondary-line}`ATmega328` - -{bdg-info-line}`low-power` -:::: - -::::: -:::::: -::::::: - - -## sphinx{design} Tabs - -For basic "tabs" needs. - -### Documentation -- [sphinx{design} » Tabs](inv:design#sd-tabs) - -### Examples - -::::{tab-set} - -:::{tab-item} Label1 -Content 1 -::: - -:::{tab-item} Label2 -Content 2 -::: - -:::: - - -## sphinx-inline-tabs - -For more advanced "tabs" needs. - -### Documentation - -https://sphinx-inline-tabs.readthedocs.io/ - -### Examples - -#### Basics -```{tab} Label1 -Content 1 -``` - -```{tab} Label2 -Content 2 -``` - -#### Code tabs -````{tab} Python -```python -print("Hello World!") -``` - -It's pretty simple! -```` - -````{tab} C++ -```cpp -#include - -int main() { - std::cout << "Hello World!" << std::endl; -} -``` - -More code, but it works too! -```` - -````{tab} Text -```none -Hello World! -``` - -Why not. -```` - -#### Synchronized -````{tab} Windows -```console -$ py -m pip install sphinx -``` -```` - -````{tab} Unix (MacOS / Linux) -```console -$ python -m pip install sphinx -``` -```` - -````{tab} Windows -:new-set: -```console -$ make.bat html -``` -```` - -````{tab} Unix (MacOS / Linux) -```console -$ make html -``` -```` - - -#### Nested -````{tab} Windows -```{tab} Command prompt -`cmd.exe` -``` -```{tab} Powershell -`ps2.exe` -``` -```` - -````{tab} Unix (MacOS / Linux) - -As can be seen on the other tab, the tab sets will "join" when there's -no text between different levels of tabs. Adding text between them -will space them out. - -```{tab} Bash -`bash` -``` -```{tab} Zsh -`zsh` -``` -```{tab} Fish -`fish` -``` -```{tab} Powershell -`ps2` -``` -```` - - -## Buttons - -### Documentation -- [sphinx{design} » Buttons](inv:design#buttons) - -### Examples -```{button-link} https://example.com -:color: primary -:shadow: -``` - -```{button-link} https://example.com -:color: primary -:outline: -``` - -```{button-link} https://example.com -:color: secondary -:expand: -``` - - -## Icons - -### Documentation -- [sphinx{design} » Icons](inv:design#icons) - -### Examples - -#### Octicon Icons - -A coloured icon: {octicon}`report;1em;sd-text-info`, some more text. - -- Alert: {octicon}`alert` -- Mention: {octicon}`mention` - -#### Material Design Icons - -- regular icon: {material-regular}`data_exploration;2em`, some more text -- A coloured regular icon: {material-regular}`settings;3em;sd-text-success`, some more text. -- A coloured outline icon: {material-outlined}`settings;3em;sd-text-success`, some more text. -- A coloured sharp icon: {material-sharp}`settings;3em;sd-text-success`, some more text. -- A coloured round icon: {material-round}`settings;3em;sd-text-success`, some more text. -- A coloured two-tone icon: {material-twotone}`settings;3em;sd-text-success`, some more text. -- A fixed size icon: {material-regular}`data_exploration;24px`, some more text. - -#### FontAwesome Icons - -- An icon {fas}`spinner;sd-text-primary`, some more text. -- An icon {fab}`github`, some more text. -- An icon {fab}`gitkraken;sd-text-success fa-xl`, some more text. -- An icon {fas}`skull;sd-text-danger`, some more text. - - -## Todo items - -```{todo} -Foo bar baz. -``` diff --git a/docs/design-restructuredtext.rst b/docs/design-restructuredtext.rst deleted file mode 100644 index 10d6e7eb7..000000000 --- a/docs/design-restructuredtext.rst +++ /dev/null @@ -1,272 +0,0 @@ -.. _design-elements-restructuredtext: - -################################# -Design elements: reStructuredText -################################# - - -************************** -Grid layout, cards, badges -************************** - -Documentation -============= - -- :ref:`sphinx{design} » Grids ` -- :ref:`sphinx{design} » Cards ` -- :ref:`sphinx{design} » Badges ` - -Examples -======== -A composite component offering a title, description text, and both verbose and short tags. -It is suitable for authoring pages enumerating items with dense information, without -the maintenance nightmares of tables. - -.. grid:: 1 - :margin: 0 - :padding: 0 - - .. grid-item-card:: - - .. grid:: 2 - :margin: 0 - :padding: 0 - - .. grid-item:: - :columns: 8 - - `multihop-firmware `_ - - A flexible software breadboard for ISM RF packet radio nodes, relays, and gateways. - - **Date:** 2015 - **Source:** multihop.ino - - .. grid-item:: - :columns: 4 - - :bdg-primary-line:`rf69` :bdg-primary-line:`rf96` :bdg-primary-line:`lora` :bdg-primary-line:`beradio` - - :bdg-success-line:`hx711` :bdg-success-line:`ds18b20` :bdg-success-line:`dht22` - - :bdg-secondary-line:`ATmega328` - - :bdg-info-line:`low-power` - - - -******************* -sphinx{design} Tabs -******************* - -For basic "tabs" needs. - -Documentation -============= -- :ref:`sphinx{design} » Tabs ` - -Examples -======== - -.. tab-set:: - - .. tab-item:: Label1 - - Content 1 - - .. tab-item:: Label2 - - Content 2 - - -****************** -sphinx-inline-tabs -****************** - -For more advanced "tabs" needs. - -Documentation -============= - -https://sphinx-inline-tabs.readthedocs.io/ - -Examples -======== - -Basics ------- - -.. tab:: Label1 - - Content 1 - -.. tab:: Label2 - - Content 2 - -Code tabs ---------- - -.. tab:: Python - - .. code-block:: python - - print("Hello World!") - - It's pretty simple! - -.. tab:: C++ - - .. code-block:: cpp - - #include - - int main() { - std::cout << "Hello World!" << std::endl; - - } - - More code, but it works too! - -.. tab:: Text - - .. code-block:: none - - Hello World! - - Why not. - -Synchronized ------------- - -.. tab:: Windows - - .. code-block:: console - - $ py -m pip install sphinx - -.. tab:: Unix (MacOS / Linux) - - .. code-block:: console - - $ python -m pip install sphinx - - -.. tab:: Windows - :new-set: - - .. code-block:: console - - $ make.bat html - -.. tab:: Unix (MacOS / Linux) - - .. code-block:: console - - $ make html - -Nested ------- - -.. tab:: Windows - - .. tab:: Command prompt - - ``cmd.exe`` - - .. tab:: Powershell - - ``ps2.exe`` - - -.. tab:: Unix (MacOS / Linux) - - As can be seen on the other tab, the tab sets will "join" when there's - no text between different levels of tabs. Adding text between them - will space them out. - - .. tab:: Bash - - ``bash`` - - .. tab:: Zsh - - ``zsh`` - - .. tab:: Fish - - ``fish`` - - .. tab:: Powershell - - ``ps2`` - - -******* -Buttons -******* - -Documentation -============= -- :ref:`sphinx{design} » Buttons ` - -Examples -======== -.. button-link:: https://example.com - :color: primary - :shadow: - -.. button-link:: https://example.com - :color: primary - :outline: - -.. button-link:: https://example.com - :color: secondary - :expand: - - - -***** -Icons -***** - -Documentation -============= -- :ref:`sphinx{design} » Icons ` - -Examples -======== - -Octicon Icons -------------- - -A coloured icon: :octicon:`report;1em;sd-text-info`, some more text. - -- Alert: :octicon:`alert` -- Mention: :octicon:`mention` - -Material Design Icons ---------------------- - -- regular icon: :material-regular:`data_exploration;2em`, some more text -- A coloured regular icon: :material-regular:`settings;3em;sd-text-success`, some more text. -- A coloured outline icon: :material-outlined:`settings;3em;sd-text-success`, some more text. -- A coloured sharp icon: :material-sharp:`settings;3em;sd-text-success`, some more text. -- A coloured round icon: :material-round:`settings;3em;sd-text-success`, some more text. -- A coloured two-tone icon: :material-twotone:`settings;3em;sd-text-success`, some more text. -- A fixed size icon: :material-regular:`data_exploration;24px`, some more text. - -FontAwesome Icons ------------------ - -- An icon :fas:`spinner;sd-text-primary`, some more text. -- An icon :fab:`github`, some more text. -- An icon :fab:`gitkraken;sd-text-success fa-xl`, some more text. -- An icon :fas:`skull;sd-text-danger`, some more text. - - -Todo items -========== -.. todo:: - - Foo bar baz. diff --git a/docs/index.rst b/docs/index.rst index 59eb2efb8..dd3c6db1c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,16 +4,17 @@ CrateDB documentation theme ########################### + ***** About ***** -A theme component for the `Sphinx static documentation generator`_. +A theme component for the `Sphinx static documentation generator`_ used by +all the Crate.io documentation projects. Examples: -Example documentation sections: +- `CrateDB Reference`_ +- `CrateDB Python Client`_ -- https://crate.io/docs/crate/reference/ -- https://crate.io/docs/python/en/latest/ ******** Overview @@ -21,8 +22,36 @@ Overview This section outlines a few features, elements, and style-guides by example. -Classic Sphinx / reStructuredText -================================= + +Modernized +========== + +A side-by-side gallery demonstrating both reStructuredText and Markedly +Structured Text syntax. + +.. grid:: + + .. grid-item:: + :columns: 6 + + .. toctree:: + :titlesonly: + + rst/index + + .. grid-item:: + :columns: 6 + + .. toctree:: + :titlesonly: + + myst/index + + +Legacy +====== + +The legacy feature gallery exclusively uses reStructuredText. .. toctree:: :maxdepth: 1 @@ -39,18 +68,6 @@ Classic Sphinx / reStructuredText glossary -Modern components -================= - -.. toctree:: - :maxdepth: 1 - - myst-overview - design-markdown - design-restructuredtext - mermaid-diagrams-markdown - mermaid-diagrams-restructuredtext - ******* Details @@ -84,6 +101,8 @@ How to improve this documentation: Assurance* (QA) workflow, see the `developer guide`_. +.. _CrateDB Python Client: https://crate.io/docs/python/ +.. _CrateDB Reference: https://crate.io/docs/crate/reference/ .. _developer guide: https://github.com/crate/crate-docs-theme/blob/main/DEVELOP.rst .. _report an issue: https://github.com/crate/crate-docs-theme/issues/new .. _Sphinx static documentation generator: https://www.sphinx-doc.org/ diff --git a/docs/myst-overview.md b/docs/myst-overview.md deleted file mode 100644 index 8d28d3836..000000000 --- a/docs/myst-overview.md +++ /dev/null @@ -1,136 +0,0 @@ -# Overview about MyST - Markedly Structured Text - -## About - -> A Sphinx and Docutils extension to parse MyST, a rich and extensible flavour -> of Markdown for authoring technical and scientific documentation. -> -> -- https://myst-parser.readthedocs.io/ - -[MyST](https://myst-parser.readthedocs.io/) is a strict superset of the -[CommonMark syntax specification](https://spec.commonmark.org/). -It adds features focussed on scientific and technical documentation authoring. {fas}`star2` - - -### Details - -Roles and directives provide a way to extend the syntax of MyST in an unbound -manner, by interpreting a chunk of text as a specific type of markup, according -to its name. -Directives syntax is defined with triple-backticks and curly-brackets, effectively -a Markdown code fence. - --– [Roles and Directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html) - -**Example** - -> ![image|297x168](https://global.discourse-cdn.com/business7/uploads/crate/original/1X/d61bae27e7ce2ca04ab7ba78954153b885f2548e.png) - - -## Overview - -### Inline quotes / citations - -> This text should be quoted. - -### Cross-references - -Being able to use cross-references appropriately, i.e. optimally linking between -documentation resources, even across projects, is important for documentation -authoring. Please refer to [MyST cross-references](inv:myst#syntax/referencing), -in order to learn about how this works using the Markdown markup language. - -By using cross-references properly, maintenance efforts regarding broken links will -be greatly reduced, because all target references will be validated at build time. -See also [How to use cross-references with Sphinx]. - -[How to use cross-references with Sphinx]: https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html - - -### Images and figures - -#### Documentation -- [sphinx{design} » Images and figures](inv:myst#syntax/images_and_figures) -- {doc}`sphinx{design} » Images and figures ` - -#### Standard - -The standard Markdown syntax for images. - -![MyST logo](_static/myst-logo-wide.svg) - -#### Adjusting attributes -The `attrs_inline` extension can be used to add attributes to an inline image, -for example, to resize/scale it. - -![MyST logo](_static/myst-logo-wide.svg){.bg-warning w=100px align=center} - -#### Block level -To create a block image, use the `image` directive. -```{image} https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg -:alt: fishy -:class: bg-primary -:width: 200px -:align: center -``` - - -#### Figures (images with captions) - -To create a figure, use the `figure` directive. - -```{figure} _static/myst-logo-wide.png -:scale: 50 % -:alt: The MyST logo. - -This is the caption of the figure (a simple paragraph). - -The legend consists of all elements after the caption. In this -case, the legend consists of this paragraph and the following -table: - -| Symbol | Meaning | -| ------ | ------- | -| :logo: | MyST | -``` - - -### Subfigures - -Documentation: https://sphinx-subfigure.readthedocs.io/ - -:::{subfigure} AA|BC -:layout-sm: A|B|C -:gap: 8px -:subcaptions: above -:name: myfigure -:class-grid: outline - -```{image} https://sphinx-subfigure.readthedocs.io/en/latest/_images/A.png -:height: 100px -:alt: Image A -``` - -```{image} https://sphinx-subfigure.readthedocs.io/en/latest/_images/B.png -:height: 100px -:alt: Image B -``` - -```{image} https://sphinx-subfigure.readthedocs.io/en/latest/_images/C.png -:height: 100px -:alt: Image C -``` - -::: - - -## History - The great dilemma - -For a long time, the power of the Sphinx documentation generator was only available -to people writing documentation in reStructuredText. Because Markdown gained -significant popularity in recent years, the community was in a big dilemma, and -surely there have been endless Programming Language Wars-style discussions about -using reStructuredText vs. Markdown for documentation authoring. - -This dilemma has come to an end with MyST now, aiming to follow up on the success -of MySQL and mypy – naming-wise. diff --git a/docs/myst/button.md b/docs/myst/button.md new file mode 100644 index 000000000..c32fc49c0 --- /dev/null +++ b/docs/myst/button.md @@ -0,0 +1,20 @@ +# Buttons + +## Documentation +- [sphinx{design} » Buttons](inv:sd#buttons) + +## Examples +```{button-link} https://example.com +:color: primary +:shadow: +``` + +```{button-link} https://example.com +:color: primary +:outline: +``` + +```{button-link} https://example.com +:color: secondary +:expand: +``` diff --git a/docs/myst/crossref.md b/docs/myst/crossref.md new file mode 100644 index 000000000..d6ec32053 --- /dev/null +++ b/docs/myst/crossref.md @@ -0,0 +1,12 @@ +# Cross-references + +Being able to use cross-references appropriately, i.e. optimally linking between +documentation resources, even across projects, is important for documentation +authoring. Please refer to [MyST cross-references](inv:myst#syntax/referencing), +in order to learn about how this works using the Markdown markup language. + +By using cross-references properly, maintenance efforts regarding broken links will +be greatly reduced, because all target references will be validated at build time. +See also [How to use cross-references with Sphinx]. + +[How to use cross-references with Sphinx]: https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html diff --git a/docs/myst/icon.md b/docs/myst/icon.md new file mode 100644 index 000000000..7da119315 --- /dev/null +++ b/docs/myst/icon.md @@ -0,0 +1,30 @@ +# Icons + +## Documentation +- [sphinx{design} » Icons](inv:sd#icons) + +## Examples + +### Octicon Icons + +A coloured icon: {octicon}`report;1em;sd-text-info`, some more text. + +- Alert: {octicon}`alert` +- Mention: {octicon}`mention` + +### Material Design Icons + +- regular icon: {material-regular}`data_exploration;2em`, some more text +- A coloured regular icon: {material-regular}`settings;3em;sd-text-success`, some more text. +- A coloured outline icon: {material-outlined}`settings;3em;sd-text-success`, some more text. +- A coloured sharp icon: {material-sharp}`settings;3em;sd-text-success`, some more text. +- A coloured round icon: {material-round}`settings;3em;sd-text-success`, some more text. +- A coloured two-tone icon: {material-twotone}`settings;3em;sd-text-success`, some more text. +- A fixed size icon: {material-regular}`data_exploration;24px`, some more text. + +### FontAwesome Icons + +- An icon {fas}`spinner;sd-text-primary`, some more text. +- An icon {fab}`github`, some more text. +- An icon {fab}`gitkraken;sd-text-success fa-xl`, some more text. +- An icon {fas}`skull;sd-text-danger`, some more text. diff --git a/docs/myst/image-figure.md b/docs/myst/image-figure.md new file mode 100644 index 000000000..ac1c5b155 --- /dev/null +++ b/docs/myst/image-figure.md @@ -0,0 +1,75 @@ +# Images and figures + +## Documentation +- [sphinx{design} » Images and figures](inv:myst#syntax/images_and_figures) +- {doc}`sphinx{design} » Images and figures ` + +## Standard + +The standard Markdown syntax for images. + +![MyST logo](../_static/myst-logo-wide.svg) + +## Adjusting attributes +The `attrs_inline` extension can be used to add attributes to an inline image, +for example, to resize/scale it. + +![MyST logo](../_static/myst-logo-wide.svg){.bg-warning w=100px align=center} + +## Block level +To create a block image, use the `image` directive. +```{image} https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg +:alt: fishy +:class: bg-primary +:width: 200px +:align: center +``` + + +## Figures (images with captions) + +To create a figure, use the `figure` directive. + +```{figure} ../_static/myst-logo-wide.png +:scale: 50 % +:alt: The MyST logo. + +This is the caption of the figure (a simple paragraph). + +The legend consists of all elements after the caption. In this +case, the legend consists of this paragraph and the following +table: + +| Symbol | Meaning | +| ------ | ------- | +| :logo: | MyST | +``` + + +## Subfigures + +Documentation: https://sphinx-subfigure.readthedocs.io/ + +:::{subfigure} AA|BC +:layout-sm: A|B|C +:gap: 8px +:subcaptions: above +:name: myfigure +:class-grid: outline + +```{image} https://sphinx-subfigure.readthedocs.io/en/latest/_images/A.png +:height: 100px +:alt: Image A +``` + +```{image} https://sphinx-subfigure.readthedocs.io/en/latest/_images/B.png +:height: 100px +:alt: Image B +``` + +```{image} https://sphinx-subfigure.readthedocs.io/en/latest/_images/C.png +:height: 100px +:alt: Image C +``` + +::: diff --git a/docs/myst/index.md b/docs/myst/index.md new file mode 100644 index 000000000..3a57d501d --- /dev/null +++ b/docs/myst/index.md @@ -0,0 +1,10 @@ +# Using Markedly Structured Text (MyST) + +:::{toctree} +:titlesonly: +:glob: + +introduction +sphinx-design +* +::: diff --git a/docs/myst/infocard.md b/docs/myst/infocard.md new file mode 100644 index 000000000..9e604bd3e --- /dev/null +++ b/docs/myst/infocard.md @@ -0,0 +1,99 @@ +# Info Card + + +## About + +The [](inv:sde#infocard-directive) is a composite web element from [](inv:sde:*:label#index). + +It is a composite component offering a title, description text, and both verbose +and short tags, or other toolkit elements. It is suitable for authoring pages +enumerating items with dense information, without the maintenance nightmares of tables. + + +## Examples + +### Example 1 + +::::{info-card} + +:::{grid-item} +:columns: 8 +[example.org/beagles](https://example.org/beagles) + +A module for collecting votes from beagles, \ +and for consolidating them. + +**Author:** C. Schultz, Universal Features Syndicate \ +**Contact:** Los Angeles, CA; +::: + +:::{grid-item} +:columns: 4 + +{tags-primary}`foo, bar` + +{tags-success}`baz` + +{tags-secondary}`qux` + +{tags-info}`anything` +::: + +:::: + + +### Example 2 + +::::{info-card} + +:::{grid-item} +:columns: 8 +[multihop-firmware](https://hiveeyes.org/docs/arduino/firmware/backdoor/multihop/README.html) + +A flexible software breadboard for ISM RF packet radio nodes, relays, and gateways. + +| **Date:** 2015 +| **Source:** multihop.ino +::: + +:::{grid-item} +:columns: 4 + +{tags-primary}`rf69, rf96, lora, beradio` + +{tags-success}`hx711, ds18b20, dht22` + +{tags-secondary}`ATmega328` + +{tags-info}`low-power` +::: + +:::: + + +### Example 3 + +:::::{info-card} + +::::{grid-item} +:columns: 8 +:class: sd-align-major-spaced +#### Curated picture of the day + +A mountain goat with long horns standing on a grassy hill. + +:::{div} text-small +**Author:** Jaromír Kalina, [@jkalinaofficial](https://unsplash.com/@jkalinaofficial) \ +**Contact:** Czech Republic, \ +**Exposé:** https://unsplash.com/photos/spdQ1dVuIHw \ +**Source:** [Unsplash -- The internet’s source for visuals](https://unsplash.com/) +::: +:::: + +::::{grid-item} +:columns: 4 + +[![](https://unsplash.com/photos/spdQ1dVuIHw/download?ixid=M3wxMjA3fDB8MXxhbGx8fHx8fHx8fHwxNjg5Nzg4MTEzfA&force=true&w=640)](https://unsplash.com/photos/spdQ1dVuIHw) +:::: + +::::: diff --git a/docs/myst/introduction.md b/docs/myst/introduction.md new file mode 100644 index 000000000..9722870af --- /dev/null +++ b/docs/myst/introduction.md @@ -0,0 +1,40 @@ +# MyST introduction + + +## About + +> A Sphinx and Docutils extension to parse MyST, a rich and extensible flavour +> of Markdown for authoring technical and scientific documentation. +> +> -- https://myst-parser.readthedocs.io/ + +[MyST](https://myst-parser.readthedocs.io/) is a strict superset of the +[CommonMark syntax specification](https://spec.commonmark.org/). +It adds features focussed on scientific and technical documentation authoring. {fas}`star2` + + +## Details + +Roles and directives provide a way to extend the syntax of MyST in an unbound +manner, by interpreting a chunk of text as a specific type of markup, according +to its name. +Directives syntax is defined with triple-backticks and curly-brackets, effectively +a Markdown code fence. + +-– [Roles and Directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html) + +**Example** + +> ![image|297x168](https://global.discourse-cdn.com/business7/uploads/crate/original/1X/d61bae27e7ce2ca04ab7ba78954153b885f2548e.png) + + +## History - The great dilemma + +For a long time, the power of the Sphinx documentation generator was only available +to people writing documentation in reStructuredText. Because Markdown gained +significant popularity in recent years, the community was in a big dilemma, and +surely there have been endless Programming Language Wars-style discussions about +using reStructuredText vs. Markdown for documentation authoring. + +This dilemma has come to an end with MyST now, aiming to follow up on the success +of MySQL and mypy – naming-wise. diff --git a/docs/mermaid-diagrams-markdown.md b/docs/myst/mermaid.md similarity index 92% rename from docs/mermaid-diagrams-markdown.md rename to docs/myst/mermaid.md index 075478da7..461ee5d15 100644 --- a/docs/mermaid-diagrams-markdown.md +++ b/docs/myst/mermaid.md @@ -1,4 +1,4 @@ -# Mermaid diagrams: Markdown +# Mermaid diagrams ## About @@ -29,5 +29,5 @@ sequenceDiagram ``` ### Flowchart diagram -```{mermaid} _static/mermaid-example.mmd +```{mermaid} ../_static/mermaid-example.mmd ``` diff --git a/docs/myst/misc.md b/docs/myst/misc.md new file mode 100644 index 000000000..5ffdd43de --- /dev/null +++ b/docs/myst/misc.md @@ -0,0 +1,13 @@ +# Miscellaneous + + +## Inline quotes / citations + +> This text should be quoted. + + +## Todo items + +```{todo} +Foo bar baz. +``` diff --git a/docs/myst/sphinx-design.md b/docs/myst/sphinx-design.md new file mode 100644 index 000000000..1516ee6b8 --- /dev/null +++ b/docs/myst/sphinx-design.md @@ -0,0 +1,9 @@ +(sphinx-design-myst)= +# sphinx-design, using MyST + +## Grid layout, cards, badges + +### Documentation +- [sphinx{design} » Grids](inv:sd#sd-grids) +- [sphinx{design} » Cards](inv:sd#sd-cards) +- [sphinx{design} » Badges](inv:sd#badges) diff --git a/docs/myst/tab.md b/docs/myst/tab.md new file mode 100644 index 000000000..283bf7713 --- /dev/null +++ b/docs/myst/tab.md @@ -0,0 +1,128 @@ +# Tabs + +## sphinx{design} Tabs + +For basic "tabs" needs. + +### Documentation +- [sphinx{design} » Tabs](inv:sd#sd-tabs) + +### Examples + +::::{tab-set} + +:::{tab-item} Label1 +Content 1 +::: + +:::{tab-item} Label2 +Content 2 +::: + +:::: + + +## sphinx-inline-tabs + +For more advanced "tabs" needs. + +### Documentation + +https://sphinx-inline-tabs.readthedocs.io/ + +### Examples + +#### Basics +```{tab} Label1 +Content 1 +``` + +```{tab} Label2 +Content 2 +``` + +#### Code tabs +````{tab} Python +```python +print("Hello World!") +``` + +It's pretty simple! +```` + +````{tab} C++ +```cpp +#include + +int main() { + std::cout << "Hello World!" << std::endl; +} +``` + +More code, but it works too! +```` + +````{tab} Text +```none +Hello World! +``` + +Why not. +```` + +#### Synchronized +````{tab} Windows +```console +$ py -m pip install sphinx +``` +```` + +````{tab} Unix (MacOS / Linux) +```console +$ python -m pip install sphinx +``` +```` + +````{tab} Windows +:new-set: +```console +$ make.bat html +``` +```` + +````{tab} Unix (MacOS / Linux) +```console +$ make html +``` +```` + + +#### Nested +````{tab} Windows +```{tab} Command prompt +`cmd.exe` +``` +```{tab} Powershell +`ps2.exe` +``` +```` + +````{tab} Unix (MacOS / Linux) + +As can be seen on the other tab, the tab sets will "join" when there's +no text between different levels of tabs. Adding text between them +will space them out. + +```{tab} Bash +`bash` +``` +```{tab} Zsh +`zsh` +``` +```{tab} Fish +`fish` +``` +```{tab} Powershell +`ps2` +``` +```` diff --git a/docs/myst/table.md b/docs/myst/table.md new file mode 100644 index 000000000..29f4da273 --- /dev/null +++ b/docs/myst/table.md @@ -0,0 +1,65 @@ +# Tables + + +## About + +The [](inv:sde#gridtable-directive) is a composite web element from [](inv:sde:*:label#index). + + +## Examples + +::::{sd-table} +:widths: 2 6 4 +:row-class: top-border + +:::{sd-row} +```{sd-item} **Table name** +``` +```{sd-item} **Changes** +``` +```{sd-item} **Column type changes** +``` +::: + +:::{sd-row} +```{sd-item} pg_proc +``` +```{sd-item} +Added: prosupport, prokind, prosqlbody +
+Removed: protransform, proisagg, proiswindow +``` +```{sd-item} proargdefaults: OBJECT[] -> STRING +``` +::: + +:::{sd-row} +```{sd-item} pg_class +``` +```{sd-item} +Added: relrewrite +
+Removed: relhasoids, relhaspkey +``` +```{sd-item} relacl: OBJECT[] -> STRING[] +``` +::: + +:::{sd-row} +```{sd-item} pg_attribute +``` +```{sd-item} +Added: atthasmissing +
+Removed: attmissingval +``` +```{sd-item} spcacl: OBJECT[] -> STRING[] +``` +::: + +:::: + + +--- + +_This page is written in Markedly Structured Text (MyST Markdown)._ diff --git a/docs/rst/button.rst b/docs/rst/button.rst new file mode 100644 index 000000000..fcf9da06e --- /dev/null +++ b/docs/rst/button.rst @@ -0,0 +1,21 @@ +******* +Buttons +******* + +Documentation +============= +- :ref:`sphinx{design} » Buttons ` + +Examples +======== +.. button-link:: https://example.com + :color: primary + :shadow: + +.. button-link:: https://example.com + :color: primary + :outline: + +.. button-link:: https://example.com + :color: secondary + :expand: diff --git a/docs/rst/icon.rst b/docs/rst/icon.rst new file mode 100644 index 000000000..d2b5edfa7 --- /dev/null +++ b/docs/rst/icon.rst @@ -0,0 +1,37 @@ +***** +Icons +***** + +Documentation +============= +- :ref:`sphinx{design} » Icons ` + +Examples +======== + +Octicon Icons +------------- + +A coloured icon: :octicon:`report;1em;sd-text-info`, some more text. + +- Alert: :octicon:`alert` +- Mention: :octicon:`mention` + +Material Design Icons +--------------------- + +- regular icon: :material-regular:`data_exploration;2em`, some more text +- A coloured regular icon: :material-regular:`settings;3em;sd-text-success`, some more text. +- A coloured outline icon: :material-outlined:`settings;3em;sd-text-success`, some more text. +- A coloured sharp icon: :material-sharp:`settings;3em;sd-text-success`, some more text. +- A coloured round icon: :material-round:`settings;3em;sd-text-success`, some more text. +- A coloured two-tone icon: :material-twotone:`settings;3em;sd-text-success`, some more text. +- A fixed size icon: :material-regular:`data_exploration;24px`, some more text. + +FontAwesome Icons +----------------- + +- An icon :fas:`spinner;sd-text-primary`, some more text. +- An icon :fab:`github`, some more text. +- An icon :fab:`gitkraken;sd-text-success fa-xl`, some more text. +- An icon :fas:`skull;sd-text-danger`, some more text. diff --git a/docs/rst/index.rst b/docs/rst/index.rst new file mode 100644 index 000000000..294a49616 --- /dev/null +++ b/docs/rst/index.rst @@ -0,0 +1,11 @@ +############################ +Using reStructuredText (rST) +############################ + +.. toctree:: + :titlesonly: + :glob: + + introduction + sphinx-design + * diff --git a/docs/rst/infocard.rst b/docs/rst/infocard.rst new file mode 100644 index 000000000..f89c0d689 --- /dev/null +++ b/docs/rst/infocard.rst @@ -0,0 +1,100 @@ +######### +Info Card +######### + + +***** +About +***** + +The :ref:`sde:infocard-directive` is a composite web element from :ref:`sde:index`. + +It is a composite component offering a title, description text, and both verbose +and short tags, or other toolkit elements. It is suitable for authoring pages +enumerating items with dense information, without the maintenance nightmares of tables. + + +******** +Examples +******** + +Example 1 +========= + +.. info-card:: + + .. grid-item:: + :columns: 8 + + `example.org/beagles `_ + + | A module for collecting votes from beagles, + | and for consolidating them. + | + | **Author:** C. Schultz, Universal Features Syndicate + | **Contact:** Los Angeles, CA; + + .. grid-item:: + :columns: 4 + + :tags-primary:`foo, bar` + + :tags-success:`baz` + + :tags-secondary:`qux` + + :tags-info:`anything` + + +Example 2 +========= + +.. info-card:: + + .. grid-item:: + :columns: 8 + + `multihop-firmware `_ + + | A flexible software breadboard for ISM RF packet radio nodes, relays, and gateways. + | + | **Date:** 2015 + | **Source:** multihop.ino + + .. grid-item:: + :columns: 4 + + :tags-primary:`rf69, rf96, lora, beradio` + + :tags-success:`hx711, ds18b20, dht22` + + :tags-secondary:`ATmega328` + + :tags-info:`low-power` + + +Example 3 +========= + +.. info-card:: + + .. grid-item:: + :columns: 8 + :class: sd-align-major-spaced + + **Curated picture of the day** + + A mountain goat with long horns standing on a grassy hill. + + .. div:: text-small + + | **Author:** Jaromír Kalina, `@jkalinaofficial `_ + | **Contact:** Czech Republic, https://jkalina.carrd.co/ + | **Exposé:** https://unsplash.com/photos/spdQ1dVuIHw + | **Source:** `Unsplash -- The internet’s source for visuals `_ + + .. grid-item:: + :columns: 4 + + .. image:: https://unsplash.com/photos/spdQ1dVuIHw/download?ixid=M3wxMjA3fDB8MXxhbGx8fHx8fHx8fHwxNjg5Nzg4MTEzfA&force=true&w=640 + :target: https://unsplash.com/photos/spdQ1dVuIHw diff --git a/docs/rst/introduction.rst b/docs/rst/introduction.rst new file mode 100644 index 000000000..78b91cdd6 --- /dev/null +++ b/docs/rst/introduction.rst @@ -0,0 +1,21 @@ +################ +rST introduction +################ + +***** +About +***** + +.. todo:: + + Add some introductory content about reStructuredText. + + +********* +Resources +********* + +- `Guide to reStructuredText and Sphinx`_ + + +.. _Guide to reStructuredText and Sphinx: https://documatt.com/restructuredtext-reference/ diff --git a/docs/mermaid-diagrams-restructuredtext.rst b/docs/rst/mermaid.rst similarity index 86% rename from docs/mermaid-diagrams-restructuredtext.rst rename to docs/rst/mermaid.rst index 903462958..7e81fff67 100644 --- a/docs/mermaid-diagrams-restructuredtext.rst +++ b/docs/rst/mermaid.rst @@ -1,6 +1,6 @@ -################################## -Mermaid diagrams: reStructuredText -################################## +################ +Mermaid diagrams +################ ***** @@ -39,4 +39,4 @@ Sequence diagram Flowchart diagram ================= -.. mermaid:: _static/mermaid-example.mmd +.. mermaid:: ../_static/mermaid-example.mmd diff --git a/docs/rst/misc.rst b/docs/rst/misc.rst new file mode 100644 index 000000000..713749083 --- /dev/null +++ b/docs/rst/misc.rst @@ -0,0 +1,14 @@ +############# +Miscellaneous +############# + +Inline quotes / citations +========================= + + This text should be quoted. + +Todo items +========== +.. todo:: + + Foo bar baz. diff --git a/docs/rst/sphinx-design.rst b/docs/rst/sphinx-design.rst new file mode 100644 index 000000000..f059597ae --- /dev/null +++ b/docs/rst/sphinx-design.rst @@ -0,0 +1,17 @@ +.. _sphinx-design-rst: + +######################## +sphinx-design, using rST +######################## + + +************************** +Grid layout, cards, badges +************************** + +Documentation +============= + +- :ref:`sphinx{design} » Grids ` +- :ref:`sphinx{design} » Cards ` +- :ref:`sphinx{design} » Badges ` diff --git a/docs/rst/tab.rst b/docs/rst/tab.rst new file mode 100644 index 000000000..bdc0128e4 --- /dev/null +++ b/docs/rst/tab.rst @@ -0,0 +1,150 @@ +#### +Tabs +#### + + +******************* +sphinx{design} Tabs +******************* + +For basic "tabs" needs. + +Documentation +============= +- :ref:`sphinx{design} » Tabs ` + +Examples +======== + +.. tab-set:: + + .. tab-item:: Label1 + + Content 1 + + .. tab-item:: Label2 + + Content 2 + + +****************** +sphinx-inline-tabs +****************** + +For more advanced "tabs" needs. + +Documentation +============= + +https://sphinx-inline-tabs.readthedocs.io/ + +Examples +======== + +Basics +------ + +.. tab:: Label1 + + Content 1 + +.. tab:: Label2 + + Content 2 + +Code tabs +--------- + +.. tab:: Python + + .. code-block:: python + + print("Hello World!") + + It's pretty simple! + +.. tab:: C++ + + .. code-block:: cpp + + #include + + int main() { + std::cout << "Hello World!" << std::endl; + + } + + More code, but it works too! + +.. tab:: Text + + .. code-block:: none + + Hello World! + + Why not. + +Synchronized +------------ + +.. tab:: Windows + + .. code-block:: console + + $ py -m pip install sphinx + +.. tab:: Unix (MacOS / Linux) + + .. code-block:: console + + $ python -m pip install sphinx + + +.. tab:: Windows + :new-set: + + .. code-block:: console + + $ make.bat html + +.. tab:: Unix (MacOS / Linux) + + .. code-block:: console + + $ make html + +Nested +------ + +.. tab:: Windows + + .. tab:: Command prompt + + ``cmd.exe`` + + .. tab:: Powershell + + ``ps2.exe`` + + +.. tab:: Unix (MacOS / Linux) + + As can be seen on the other tab, the tab sets will "join" when there's + no text between different levels of tabs. Adding text between them + will space them out. + + .. tab:: Bash + + ``bash`` + + .. tab:: Zsh + + ``zsh`` + + .. tab:: Fish + + ``fish`` + + .. tab:: Powershell + + ``ps2`` diff --git a/docs/rst/table.rst b/docs/rst/table.rst new file mode 100644 index 000000000..f2fc672b4 --- /dev/null +++ b/docs/rst/table.rst @@ -0,0 +1,50 @@ +###### +Tables +###### + + +***** +About +***** + +The :ref:`sde:gridtable-directive` is a composite web element from :ref:`sde:index`. + + +******** +Examples +******** + +.. sd-table:: + :widths: 2 6 4 + :row-class: top-border + + .. sd-row:: + .. sd-item:: **Table name** + .. sd-item:: **Changes** + .. sd-item:: **Column type changes** + + .. sd-row:: + .. sd-item:: pg_proc + .. sd-item:: + | Added: prosupport, prokind, prosqlbody + | Removed: protransform, proisagg, proiswindow + .. sd-item:: proargdefaults: OBJECT[] -> STRING + + .. sd-row:: + .. sd-item:: pg_class + .. sd-item:: + | Added: relrewrite + | Removed: relhasoids, relhaspkey + .. sd-item:: relacl: OBJECT[] -> STRING[] + + .. sd-row:: + .. sd-item:: pg_attribute + .. sd-item:: + | Added: atthasmissing + | Removed: attmissingval + .. sd-item:: spcacl: OBJECT[] -> STRING[] + + +---- + +*This page is written in reStructuredText (rST).* From 5ac637b58c9280044f14d59dc0efd13460da6b06 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 20 Jul 2023 10:10:18 +0200 Subject: [PATCH 8/8] Documentation: Fix broken links and whitespaces --- docs/myst/introduction.md | 6 +++--- docs/myst/mermaid.md | 2 +- src/crate/theme/rtd/conf/__init__.py | 3 ++- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/myst/introduction.md b/docs/myst/introduction.md index 9722870af..cdffe9511 100644 --- a/docs/myst/introduction.md +++ b/docs/myst/introduction.md @@ -8,14 +8,14 @@ > > -- https://myst-parser.readthedocs.io/ -[MyST](https://myst-parser.readthedocs.io/) is a strict superset of the +[MyST](https://myst-parser.readthedocs.io/) is a strict superset of the [CommonMark syntax specification](https://spec.commonmark.org/). It adds features focussed on scientific and technical documentation authoring. {fas}`star2` ## Details -Roles and directives provide a way to extend the syntax of MyST in an unbound +Roles and directives provide a way to extend the syntax of MyST in an unbound manner, by interpreting a chunk of text as a specific type of markup, according to its name. Directives syntax is defined with triple-backticks and curly-brackets, effectively @@ -36,5 +36,5 @@ significant popularity in recent years, the community was in a big dilemma, and surely there have been endless Programming Language Wars-style discussions about using reStructuredText vs. Markdown for documentation authoring. -This dilemma has come to an end with MyST now, aiming to follow up on the success +This dilemma has come to an end with MyST now, aiming to follow up on the success of MySQL and mypy – naming-wise. diff --git a/docs/myst/mermaid.md b/docs/myst/mermaid.md index 461ee5d15..9e9ef313b 100644 --- a/docs/myst/mermaid.md +++ b/docs/myst/mermaid.md @@ -25,7 +25,7 @@ for an introduction. sequenceDiagram participant Alice participant Bob - Alice->John: Hello John, how are you? + Alice->John: Hello John, how are you? ``` ### Flowchart diagram diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py index de43e338e..bc2b48770 100644 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/src/crate/theme/rtd/conf/__init__.py @@ -148,7 +148,8 @@ # Configure linkchecker linkcheck_ignore = [ # Breaks accessibility via JS ¯\_(ツ)_/¯ - "https://www.iso.org/obp/ui/.*" + "https://www.iso.org/obp/ui/.*", + "https://example.org/.*", ] linkcheck_retries = 3 linkcheck_timeout = 15