Overview

Pretend this is the tutorial that gives a general introduction to the library, providing usage examples and all that.

This is a stand-alone document, in this case a file named overview.md inside the project’s docs folder. So it is separate from the actual Python library in the, unimaginatively named, package folder. Both folders are right underneath the project’s root in the repo.

We have set up the API documentation as a different chapter. It is also a stand-alone document, named api.md, and is linked in the side bar on the left. Readers can go there to understand how the library is to be used in application code. That is, it documents the public API. Not every doc-string defined in package needs to show up there, only the ones that are important. So we kick things off with a general summary of the top-level objects, courtesy of the MyST-summary extension (a modified version of Sphinx’s Autosummary) extension, which links to in-depth API documentation provided by MyST-docstring (derived from Autodoc).

We can then link to objects from the API documentation, such as Class1 or action. The syntax is {any}`Class1` and {any}`action <package.action>` (as the latter reference happens to be ambiguous). This is the MyST-Markdown way of referring to the Sphinx role any, which then basically looks in any place to resolve the reference. Alternatively, we can write [`Class1`](Class1) and [`action`](Class2.action) to create links to Class1 and action with a more Markdownian syntax.

Some people like to document the API within the general documentation as they go along. So instead of just referring to Class1, they pull in its doc-string somewhere in the text:

class Class1

This is the first line in the doc-string of Class1.

It is part of module classes.

action(do='nothing')

This is a method of Class1.

Intersphinx is configured just like it is without MyST, so that we get short-hand link targets to external documentation, like to Python’s pathlib module with [`pathlib`](python:pathlib).

As opposed to reST, we can nest mark-up inside link text, like a literal. No Markdown parser has ever had a problem with that.

First steps

This is a section inside the Overview chapter. We have marked it as a possible link target by putting (first-steps)= right above the section header. MyST would also generate anchors automatically, for sections up to a given level, if we specify e.g. myst_heading_anchors = 2 in conf.py.

Here is a code example:

from package.classes import Class1

class1 = Class1()
class1.action()

We used triple back-ticks (```) to mark the code block. We could also use triple colons (:::) if we add myst_enable_extensions = ['colon_fence'] to the configuration.

MyST has nothing to do with the syntax highlighting. It works just like with Sphinx alone, and as such is defined by the theme, here Furo. Click the icon at the top right of the page to switch between dark and light mode and notice how the highlighting changes along with it. We could easily replace Furo with any of a number of Sphinx themes.