Metadata-Version: 2.1
Name: metadocs
Version: 0.4.0.1
Summary: The docs of your docs: manage sphinx documentations with mkdocs
Home-page: https://github.com/entrepreneur-interet-general/metadocs
Author: Victor Schmidt
Author-email: vsch@protonmail.com
License: AGPL
Description-Content-Type: UNKNOWN
Keywords: documentation doc sphinx mkdocs metadocs
Platform: UNKNOWN
Requires-Dist: watchdog
Requires-Dist: sphinx (>=1.7.6)
Requires-Dist: mkdocs
Requires-Dist: sphinx-rtd-theme (>=0.4.0)
Requires-Dist: mkdocs-material
Requires-Dist: pexpect
Requires-Dist: pygments

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


