Skip to main content

The docs of your docs: manage sphinx documentations with mkdocs

Project description

.. raw:: html

<p align="center">

.. raw:: html

</p>

.. 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>`__

About
=====

``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’ ``conf.py``).

.. figure:: https://i.imgur.com/OyYGmOL.png
:alt: metadocs illustration

metadocs illustration

Install
=======

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

Usage
=====

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:

::

your_home_documentation/
mkdocs.yml
docs/ # your home documentation, listing sphinx docs
index.md # mandatory file -> mkdocs's index
site/
your_project_1/
build/ # sphinx's build directory
source/ # sphinx's documentation source directory
your_project_1/ # your documented code as a package
__init__.py
your_package_1_1/
your_package_1_2/
...
your_project_2/
build/
source/
your_project_2/
__init__.py
your_package_2_1/
your_package_2_2/
...
...

**2** ``mkdocs``\ ’s ``index.md`` 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 ``__init__.py`` and use
``autodoc``:

::

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

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

If ``metadocs autodoc``\ ’s default values for the ``sphinx``
documentation don’t suit you, do update
``/path_to_your_documentation/your_project_3/source/conf.py``.

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.

Customization
-------------

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
``source/conf.py``.

Useful Resources
~~~~~~~~~~~~~~~~

- `Mkdocs’s Getting
Started <https://www.mkdocs.org/user-guide/writing-your-docs/>`__
- `Material for Mkdocs’s customization
instructions <https://squidfunk.github.io/mkdocs-material/customization/>`__
- `Material for Mkdocs’s supported extensions
list <https://squidfunk.github.io/mkdocs-material/extensions/admonition/>`__


Project details


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
metadocs-0.4.0.1-py3-none-any.whl (93.3 kB) Copy SHA256 hash SHA256 Wheel py3

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page