Skip to main content

A friendly Sphinx wrapper

Project description

📘 mudkip

PyPI PyPI - Python Version Code style: black

A friendly Sphinx wrapper.

🚧 Work in progress 🚧

Mudkip is a small wrapper around Sphinx that bundles essential tools and extensions, providing everything needed for documenting your projects.

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

  A friendly Sphinx wrapper.

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

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


Mudkip intends to provide an out-of-the-box solution for small to medium 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:

Additional features are provided through an internal extension.

  • mdinclude directive

    The built-in include directive doesn't handle markdown so mudkip provides an mdinclude directive to include markdown files.

    .. mdinclude:: ../

    It's also possible to only include a specific section of the file with the start-line and end-line options.

    .. mdinclude:: ../
      :start-line: 7
      :end-line: -3


The package can be installed with pip.

$ pip install mudkip

Getting started

After installing the package, no need to run sphinx-quickstart or to configure anything, you can immediatly run the develop command 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 recommonmark extension, allowing you to use both reStructuredText and markdown files. You can totally create an file instead if you prefer markdown over 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/dist".

$ 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.

Running doctests

Mudkip enables the sphinx.ext.doctest extension, making it possible to test interactive code examples. Try to add the following snippet to your index document:

>>> import this
The Zen of Python, by Tim Peters
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


Using Jupyter notebooks

The nbsphinx 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...

With the build command, Notebooks are executed as part of 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 further than regular Sphinx themes by running npm scripts for you if you're building your own front-end. If your docs contain a package.json file, Mudkip will invoke the appropriate npm script after running Sphinx 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.


Mudkip doesn't require any configuration. You can however overwrite some of the default settings with command-line options or a configuration file.

For instance, when running a command, you can use the --preset or -p option to overwrite the default preset with alabaster if you want to use the Alabaster theme instead of the default Read the Docs theme.

$ mudkip build --preset alabaster

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

Here is the list of all the options that can be overwritten in the config file:

  • preset

    default: "rtd"

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

  • 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/dist"

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

  • 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 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.


Contributions are welcome. This project uses poetry.

$ poetry install

The code follows the black code style.

$ poetry run black mudkip

License - MIT

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mudkip, version 0.3.6
Filename, size File type Python version Upload date Hashes
Filename, size mudkip-0.3.6-py3-none-any.whl (17.5 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size mudkip-0.3.6.tar.gz (18.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page