Package: mkinx
Aboutmkinxallows you to integrate severalsphinxdocumentation
projects into one Home Documentation listing them and allowing you to
have cross projects documentation withmkdocs.Anysphinxmodule can be used as long asmake htmlworks and the
built code is inyour_documentation/your_project/build.mkinxcomes 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 globalmkdocs.ymland in individual python projects’conf.py).Installpip install mkinxGetting StartedStart your Home Documentation with:mkinx init your_home_documentationStart the server withmkinx serveOptionnaly you can specify a port withmkinx serve-syour_portOr manually build the documentation withmkinx 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 buildUsageThe package comes with a thorough documentation by default, which you’ll
see by runningmkinx serveafter a properinit. 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:1You 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/
            ...
    ...2mkdocs’sindex.mdfile must have a# Projectssection listing them as in the exampleAlso, remember to runbuildorservecommands from your Home
Documenation’sroot folder(inyour_home_documentation/in the
example above) otherwise you may get errors sayingmkinxcan’t find
a file.Adding a Python projectmkinxcomes with a usefulautodoccommand 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 inyour_home_documentation/. Say it’s calledyour_project_3. Then you just need to go there and useautodoc:$ pwd
/path_to_your_documentation/
$ mkdir your_project_3
$ cd your_project_3
$ cp -r path/to/your_project_3 .
$ ls
your_project_3
$ mkinx autodoc
... some prints
$ ls
Makefile    source    build    your_project_3Under the hood,mkinx autodocrunssphinx-quickstart, updates
default values to be compatible to themkinxsetting, runssphinx-autoapi, rearranges the created.rstfiles, builds the
documentation withmkinx buildand updated the Home Documentation’sindex.mdfile to listyour_project_3.Ifmkinx autodoc’s default values for thesphinxdocumentation
don’t suit you, do updateyour_project_3/conf.py.Manual addition of a built documentationIf you dont want tomkinx autodoc, you may use any sphinx
configuration you want. Just keep in mind thatmkinxwill runmake htmlfrom your project’s directory (so check that this works)
andmkinx serveexpects to find a file calledindex.htmlin a
directory calledbuild/in your project.CustomizationYou may use any other theme for instance. To usemkdocs-naturejust:pip install mkdocs-natureThen change this inmkdocs.yaml:theme: natureand finally:mkdocs buildEdit the global configuration inmkdocs.yamland each project’s insource/conf.py.Useful ResourcesMkdocs’s Getting
StartedMaterial for Mkdocs’s customization
instructionsMaterial for Mkdocs’s supported extensions
list