mudkip 0.2.4

A friendly Sphinx wrapper

📘 mudkip

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.

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 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:

• sphinx.ext.autodoc for generating documentation from docstrings
• sphinx.ext.napoleon for Google-style and NumPy-style docstrings support
• sphinx_autodoc_typehints for pulling type information from Python 3 annotations
• sphinx.ext.doctest for doctest support
• recommonmark for markdown support
• nbsphinx for Jupyter notebook support

Installation

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 index.md 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
<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 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.

Configuration

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

Contributing

Contributions are welcome. This project uses poetry.

$ poetry install

The code follows the black code style.

$ poetry run black mudkip

---

License - MIT