A friendly Sphinx wrapper
Project description
📘 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 docstringssphinx.ext.napoleon
for Google-style and NumPy-style docstrings supportsphinx_autodoc_typehints
for pulling type information from Python 3 annotationssphinx.ext.doctest
for doctest supportsphinx.ext.autosectionlabel
for referencing sections with their titlerecommonmark
for markdown support andAutoStructify
nbsphinx
for Jupyter notebook support
Additional features are provided through an internal extension.
-
mdinclude
directiveThe built-in
include
directive doesn't handle markdown so mudkip provides anmdinclude
directive to include markdown files... mdinclude:: ../README.md
It's also possible to only include a specific section of the file with the
start-line
andend-line
options... mdinclude:: ../README.md :start-line: 7 :end-line: -3
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 anindex.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.
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.
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 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
andalabaster
presets enable the development server and configure Sphinx to use thedirhtml
builder. Thertd
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 totrue
will tell mudkip to display the entire Sphinx output as well as the Jupyter output when running thedevelop
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
optionMudkip 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
optionThe project title used by Sphinx when building the documentation.
-
copyright
default: The current year followed by the value of the
author
optionThe 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
optionThe 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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.