Mudkip

A friendly Sphinx wrapper.

Mudkip is a small wrapper around Sphinx that bundles essential tools and extensions, providing everything needed for building rich documentation for Python projects.

$ mudkip --help
Usage: mudkip [OPTIONS] COMMAND [ARGS]...

  A friendly Sphinx wrapper.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  build    Build documentation.
  clean    Remove output directory.
  develop  Start development server.
  init     Initialize documentation.
  test     Test documentation.

Features

Mudkip intends to provide an out-of-the-box solution for most Python projects. The command-line utility lets you build and check your documentation, launch a development server with live reloading, run doctests and more!

Mudkip enables the following Sphinx extensions:

• sphinx.ext.autodoc for generating documentation from docstrings
• sphinx.ext.napoleon for Google-style and NumPy-style docstring support
• sphinx.ext.doctest for doctest support
• sphinx.ext.autosectionlabel for referencing sections with their title
• sphinx.ext.intersphinx for linking to other projects’ documentation
• sphinx.ext.githubpages when deploying to GitHub Pages
• myst_parser for markdown support
• myst_nb for Jupyter notebook support
• sphinxcontrib.mermaid for Mermaid graphs and flowcharts

Installation

The package can be installed with pip.

$ pip install mudkip

Getting started

You can forget everything about sphinx-quickstart, conf.py and intimidating Makefiles. After installing the package, no need to configure anything you can run the develop command right away and start writing docs.

$ mudkip develop
Watching "docs"...
Server running on http://localhost:5500

The command will create the "docs" directory if it doesn't already exist and launch a development server with live reloading. If you create an index.rst file and open the link in your browser, you'll see that mudkip uses the Read the Docs theme by default.

Note that mudkip enables the myst_parser extension, allowing you to use both reStructuredText and markdown files. You can create an index.md file if you want to use markdown instead of reStructuredText.

Press Ctrl+C at any time to exit.

Building and checking documentation

The build command invokes the dirhtml builder and builds your documentation. By default, the generated files are in "docs/_build".

$ mudkip build

Running the command with the --check or -c flag will exit with code 1 if Sphinx reports any error or warning.

$ mudkip build --check

The --check flag also makes sure that there are no broken links by running the linkcheck builder on your documentation. You can disable this with the --skip-broken-links flag.

The build command also features a really handy flag if you're deploying the documentation to GitHub Pages. The --update-gh-pages flag will invoke Sphinx with the sphinx.ext.githubpages extension and then force push the output directory to the gh-pages branch of your repository.

$ mudkip build --update-gh-pages

The remote branch will be created if it doesn't already exist.

Running doctests

Mudkip enables the sphinx.ext.doctest extension, making it possible to test interactive code examples. You can try it out by adding the following code snippet to your index document:

.. doctest::

    >>> import this
    The Zen of Python, by Tim Peters
    <BLANKLINE>
    Beautiful is better than ugly.
    ...

The test command will run the code example and make sure that the output matches the documentation.

$ mudkip test
Testing "docs"...

Document: index
---------------
1 items passed all tests:
   1 tests in default
1 tests in 1 items.
1 passed and 0 failed.
Test passed.

Doctest summary
===============
    1 test
    0 failures in tests
    0 failures in setup code
    0 failures in cleanup code

Passed.

Using Jupyter notebooks

The myst-nb extension provides support for Jupyter notebooks. This means that in addition to .rst and .md files, Sphinx will also generate pages for .ipynb files.

The develop command can launch the Jupyter notebook in the "docs" directory and open it in your browser with the --notebook or -n flag.

$ mudkip develop --notebook
Watching "docs"...
Server running on http://localhost:5500
Notebook running on http://localhost:8888/?token=5e64df6...

Notebooks are executed during the build process. The --check flag will make sure that there are no uncaught exceptions in any cell.

Integration with npm and yarn

Mudkip can help you go beyond traditional Sphinx themes by running npm scripts for you and integrate with the build process of a custom front-end. If your docs contain a package.json file, Mudkip will run Sphinx and then invoke the appropriate npm script using your preferred npm client.

$ mudkip build

Here, Mudkip would try to run either npm run build or yarn build before exiting the command. Similarly, mudkip clean would try to run either npm run clean or yarn clean.

$ mudkip develop

The develop command will try to run one of the following scripts: develop, dev, start or serve. If you don't have a dedicated script to run your project in development mode, Mudkip will simply execute the build script after running Sphinx each time you make a modification.

Configuration

Mudkip doesn't really require any configuration but you can change some of the default settings with command-line options or a configuration file.

For example, when running a command, you can set the --preset or -p option to furo if you want to use the Furo theme instead of the default Read the Docs theme.

$ mudkip build --preset furo

It's also possible to change the default source and output directories with the --source-dir and --output-dir options respectively.

$ mudkip build --source-dir path/to/docs --output-dir path/to/output

Passing these options to every single command can become tedious so you can use a configuration file to save your custom settings.

Running the init command will either add a [tool.mudkip] section to your pyproject.toml or create a mudkip.toml file with some basic configuration.

$ mudkip init

Available options

• preset

  default: "rtd"

  Presets configure Mudkip and Sphinx to enable specific features. The rtd, furo and alabaster presets enable the development server and configure Sphinx to use the dirhtml builder. The rtd preset changes the html theme to the Read the Docs theme and the furo preset to the Furo theme.

  The xml preset configures Sphinx to use the xml builder. This is useful for more advanced use-cases when you have a separate static site generator that can process a hierarchy of docutils documents.

• source_dir

  default: "docs"

  This is the directory containing the source files for your documentation. Sphinx is configured to use it as its source directory and when the development server is enabled, Mudkip will watch the directory for changes to rebuild your documentation.

• output_dir

  default: "docs/_build"

  The output directory is where Sphinx will output the generated files. This is also the directory served by the development server.

• base_url

  default: None

  The base url used by Sphinx when building the documentation. You can use it to specify a custom domain when deploying to GitHub Pages and make sure Sphinx generates the appropriate CNAME file.

• repository

  default: The repository field in pyproject.toml

  The repository url of the remote when updating GitHub Pages.

  If you're not using poetry, you will need to set it manually.

• verbose

  default: false

  This option can also be enabled on the command-line with the --verbose flag. Setting it to true will tell Mudkip to display the entire Sphinx output as well as the Jupyter notebook output when running the develop command with the --notebook flag.

• project_name

  default: The name of the project you're documenting in pyproject.toml

  If you're not using poetry, you will need to set it manually.

• project_dir

  default: The value of the project_name option

  Mudkip will watch the Python files in your project directory when using the development server. This enables live reloading even when you're editing docstrings.

• title

  default: The value of the project_name option

  The project title used by Sphinx when building the documentation.

• copyright

  default: The current year followed by the value of the author option

  The copyright notice used by Sphinx when building the documentation.

• author

  default: The concatenated list of authors in pyproject.toml

  If you're not using poetry, you will need to set it manually.

• version

  default: The first two numbers of the release option

  The version used by Sphinx when building the documentation.

• release

  default: The project version in pyproject.toml

  If you're not using poetry, you will need to set it manually.

• override

  default: An empty dictionary

  The override option lets you override sphinx configuration directly. You can use it to specify a custom theme or a logo for instance.

• section_label_depth

  Enables sphinx.ext.autosectionlabel and sets the autosectionlabel_maxdepth option.

Contributing

Contributions are welcome. Make sure to first open an issue discussing the problem or the new feature before creating a pull request. The project uses poetry.

$ poetry install

The code follows the black code style.

$ poetry run black mudkip

License - MIT