Package: metadocs
.. 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 builtdocumentation <#manual-addition-of-a-built-documentation>`__-  `Customization <#customization>`__-  `Useful Resources <#useful-resources>`__About=====``metadocs`` allows you to integrate several ``sphinx`` documentationprojects into one Home Documentation listing them and allowing you tohave cross projects documentation with ``mkdocs``.Any ``sphinx`` module can be used as long as ``make html`` works and thebuilt code is in ``your_documentation/your_project/build``.``metadocs`` comes with an example project and a standalone documentionso you can already get started!Default settings are that the Home Documentation will use a MaterialDesign 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 illustrationmetadocs illustrationInstall=======``metadocs`` requires python3 and mainly uses ``sphinx``, ``mkdocs`` and``watchdog`` as 3rd party libraries. Check out the `fullrequirements </requirements.txt>`__::pip install metadocsGetting Started===============Start your Home Documentation with:::metadocs init your_home_documentationStart the server with::metadocs serveOptionnaly 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 buildUsage=====The package comes with a thorough documentation by default, which you’llsee by running ``metadocs serve`` after a proper ``init``. A Read TheDocs-hosted version may arrive at some point.The built in documentation is there to help you but is in no waynecessary, you can overwrite or delete everything. **There are however 2mandatory things:****1** You have to keep this structure:::your_home_documentation/mkdocs.ymldocs/ # your home documentation, listing sphinx docsindex.md # mandatory file -> mkdocs's indexsite/your_project_1/build/ # sphinx's build directorysource/ # sphinx's documentation source directoryyour_project_1/ # your documented code as a package__init__.pyyour_package_1_1/your_package_1_2/...your_project_2/build/source/your_project_2/__init__.pyyour_package_2_1/your_package_2_2/......**2** ``mkdocs``\ ’s ``index.md`` file must have a ``# Projects``section listing them as in the exampleAlso, remember to run ``build`` or ``serve`` commands from your HomeDocumenation’s **root folder** (in ``your_home_documentation/`` in theexample above) otherwise you may get errors saying ``metadocs`` can’tfind a file.Adding a Python project-----------------------``metadocs`` comes with a useful ``autodoc`` command helping you easilyadd a new python project to your documentation.All you have to do is put the documented (Google-style docstrings) codealong 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 .$ lsyour_project_3$ metadocs autodoc... some prints$ lsMakefile    source    build    your_project_3Under the hood, ``metadocs autodoc`` runs ``sphinx-quickstart``, updatesdefault values in ``conf.py``, runs ``sphinx-apidoc``, rearranges thecreated ``.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 sphinxconfiguration 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 adirectory called ``build/`` in your project.Customization-------------You may use any other theme for instance. To use ``mkdocs-nature`` just:::pip install mkdocs-natureThen change this in ``mkdocs.yaml`` : ``theme: nature`` and finally:::mkdocs buildEdit the global configuration in ``mkdocs.yaml`` and each project’s in``source/conf.py``.Useful Resources~~~~~~~~~~~~~~~~-  `Mkdocs’s GettingStarted <https://www.mkdocs.org/user-guide/writing-your-docs/>`__-  `Material for Mkdocs’s customizationinstructions <https://squidfunk.github.io/mkdocs-material/customization/>`__-  `Material for Mkdocs’s supported extensionslist <https://squidfunk.github.io/mkdocs-material/extensions/admonition/>`__