Skip to main content

The docs of your docs: manage sphinx documentations with mkdocs

Project description

.. raw:: html

<p align="center">

.. raw:: html


.. raw:: html

<!-- TOC -->

- `About <#about>`__
- `Install <#install>`__
- `Getting Started <#getting-started>`__
- `Usage <#usage>`__

- `Adding a Python project <#adding-a-python-project>`__
- `Manual addition of a built
documentation <#manual-addition-of-a-built-documentation>`__
- `Customization <#customization>`__

- `Useful Resources <#useful-resources>`__


``metadocs`` allows you to integrate several ``sphinx`` documentation
projects into one Home Documentation listing them and allowing you to
have cross projects documentation with ``mkdocs``.

Any ``sphinx`` module can be used as long as ``make html`` works and the
built code is in ``your_documentation/your_project/build``.

``metadocs`` comes with an example project and a standalone documention
so you can already get started!

Default settings are that the Home Documentation will use a Material
Design theme and Project Documentations will use Read The Docs’s theme,
to better distinguish the hierarchy. You can change that (in the global
``mkdocs.yml`` and in individual python projects’ ````).

.. figure::
:alt: metadocs illustration

metadocs illustration


``metadocs`` requires python3 and mainly uses ``sphinx``, ``mkdocs`` and
``watchdog`` as 3rd party libraries. Check out the `full
requirements </requirements.txt>`__


pip install metadocs

Getting Started

Start your Home Documentation with:


metadocs init your_home_documentation

Start the server with


metadocs serve

Optionnaly you can specify a port with ``metadocs serve -s your_port``

You can also manually build the documentation with ``build``:


metadocs build [FLAGS]

Flags being:


-v, --verbose verbose flag (Sphinx will stay verbose)
-A, --all Build doc for all projects
-F, --force force the build, no verification asked
-o, --only_index only build projects listed in the Documentation's Home
-p, --projects [PROJECTS [PROJECTS ...]] list of projects to build


The package comes with a thorough documentation by default, which you’ll
see by running ``metadocs serve`` after a proper ``init``. A Read The
Docs-hosted version may arrive at some point.

The built in documentation is there to help you but is in no way
necessary, you can overwrite or delete everything. **There are however 2
mandatory things:**

**1** You have to keep this structure:


docs/ # your home documentation, listing sphinx docs # mandatory file -> mkdocs's index
build/ # sphinx's build directory
source/ # sphinx's documentation source directory
your_project_1/ # your documented code as a package

**2** ``mkdocs``\ ’s ```` file must have a ``# Projects``
section listing them as in the example

Also, remember to run ``build`` or ``serve`` commands from your Home
Documenation’s **root folder** (in ``your_home_documentation/`` in the
example above) otherwise you may get errors saying ``metadocs`` can’t
find a file.

Adding a Python project

``metadocs`` comes with a useful ``autodoc`` command helping you easily
add a new python project to your documentation.

All you have to do is put the documented (Google-style docstrings) code
along the documentation in ``your_home_documentation/``. Say it’s called
``your_project_3``. Then you just need to make a new directory called
``your_project_3`` go there, copy ``your_project_3``\ ’s code in there
(as a package, meaning it should include a ```` and use


$ pwd
$ mkdir your_project_3
$ cd your_project_3
$ cp -r path/to/your_project_3 .
$ ls
$ metadocs autodoc
... some prints
$ ls
Makefile source build your_project_3

Under the hood, ``metadocs autodoc`` runs ``sphinx-quickstart``, updates
default values in ````, runs ``sphinx-apidoc``, rearranges the
created ``.rst`` files, builds the documentation with ``metadocs build``
and updates the Home Documentation’s ```` file to list

If ``metadocs autodoc``\ ’s default values for the ``sphinx``
documentation don’t suit you, do update

Manual addition of a built documentation

If you don’t want to ``metadocs autodoc``, you may use any sphinx
configuration you want. Just keep in mind that ``metadocs`` will run
``make html`` from your project’s directory (so check that this works)
and ``metadocs serve`` expects to find a file called ``index.html`` in a
directory called ``build/`` in your project.


You may use any other theme for instance. To use ``mkdocs-nature`` just:


pip install mkdocs-nature

Then change this in ``mkdocs.yaml`` : ``theme: nature`` and finally:


mkdocs build

Edit the global configuration in ``mkdocs.yaml`` and each project’s in

Useful Resources

- `Mkdocs’s Getting
Started <>`__
- `Material for Mkdocs’s customization
instructions <>`__
- `Material for Mkdocs’s supported extensions
list <>`__

Project details

Download files

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

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

metadocs- (93.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page