Metadata-Version: 2.0
Name: mkinx
Version: 0.2.0
Summary: Manage sphinx documentations with mkdocs
Home-page: https://github.com/entrepreneur-interet-general/mkinx
Author: Victor Schmidt
Author-email: vsch@protonmail.com
License: GNU
Description-Content-Type: UNKNOWN
Keywords: documentation doc sphinx mkdocs mkinx
Platform: UNKNOWN
Requires-Dist: watchdog
Requires-Dist: sphinx
Requires-Dist: mkdocs
Requires-Dist: sphinx-rtd-theme
Requires-Dist: mkdocs-material
Requires-Dist: pexpect

|PyPI version|

About
=====

``mkinx`` 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_project/build``.

``mkinx`` 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
respectively ``mkdocs.yml`` and ``conf.py``).

Install
=======

::

    pip install mkinx

Getting Started
===============

Start you Home Documentation with

::

    mkinx init your_project

Start the server with

::

    mkinx serve

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

Build the documentation with

::

    mkinx 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 ``mkinx 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/
            index.md # mandatory file -> mkdocs's index
        site/
        your_project_1/
            build/ # sphinx's build directory
            source/ # sphinx's documentation source directory
            your_package_1_1/
            your_package_1_2/
            ...
        your_project_2/
            build/
            source/
            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 commands from your Home Documenation’s root folder
(in ``your_home_documentation/`` in the example above) otherwise you may
get errors saying ``mkinx`` can’t find a file.

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

.. |PyPI version| image:: https://badge.fury.io/py/mkinx.svg
   :target: https://badge.fury.io/py/mkinx


