\n\n.. raw:: html\n\n
\n\n.. raw:: html\n\n \n\n- `About <#about>`__\n- `Install <#install>`__\n- `Getting Started <#getting-started>`__\n- `Usage <#usage>`__\n\n - `Adding a Python project <#adding-a-python-project>`__\n - `Manual addition of a built\n documentation <#manual-addition-of-a-built-documentation>`__\n - `Customization <#customization>`__\n\n - `Useful Resources <#useful-resources>`__\n\nAbout\n=====\n\n``metadocs`` allows you to integrate several ``sphinx`` documentation\nprojects into one Home Documentation listing them and allowing you to\nhave cross projects documentation with ``mkdocs``.\n\nAny ``sphinx`` module can be used as long as ``make html`` works and the\nbuilt code is in ``your_documentation/your_project/build``.\n\n``metadocs`` comes with an example project and a standalone documention\nso you can already get started!\n\nDefault settings are that the Home Documentation will use a Material\nDesign theme and Project Documentations will use Read The Docs\u2019s theme,\nto better distinguish the hierarchy. You can change that (in the global\n``mkdocs.yml`` and in individual python projects\u2019 ``conf.py``).\n\n.. figure:: https://i.imgur.com/OyYGmOL.png\n :alt: metadocs illustration\n\n metadocs illustration\n\nInstall\n=======\n\n``metadocs`` requires python3 and mainly uses ``sphinx``, ``mkdocs`` and\n``watchdog`` as 3rd party libraries. Check out the `full\nrequirements `__\n\n::\n\n pip install metadocs\n\nGetting Started\n===============\n\nStart your Home Documentation with:\n\n::\n\n metadocs init your_home_documentation\n\nStart the server with\n\n::\n\n metadocs serve\n\nOptionnaly you can specify a port with ``metadocs serve -s your_port``\n\nYou can also manually build the documentation with ``build``:\n\n::\n\n metadocs build [FLAGS]\n\nFlags being:\n\n::\n\n -v, --verbose verbose flag (Sphinx will stay verbose)\n -A, --all Build doc for all projects\n -F, --force force the build, no verification asked\n -o, --only_index only build projects listed in the Documentation's Home\n -p, --projects [PROJECTS [PROJECTS ...]] list of projects to build\n\nUsage\n=====\n\nThe package comes with a thorough documentation by default, which you\u2019ll\nsee by running ``metadocs serve`` after a proper ``init``. A Read The\nDocs-hosted version may arrive at some point.\n\nThe built in documentation is there to help you but is in no way\nnecessary, you can overwrite or delete everything. **There are however 2\nmandatory things:**\n\n**1** You have to keep this structure:\n\n::\n\n your_home_documentation/\n mkdocs.yml\n docs/ # your home documentation, listing sphinx docs\n index.md # mandatory file -> mkdocs's index\n site/\n your_project_1/\n build/ # sphinx's build directory\n source/ # sphinx's documentation source directory\n your_project_1/ # your documented code as a package\n __init__.py\n your_package_1_1/\n your_package_1_2/\n ...\n your_project_2/\n build/\n source/\n your_project_2/\n __init__.py\n your_package_2_1/\n your_package_2_2/\n ...\n ...\n\n**2** ``mkdocs``\\ \u2019s ``index.md`` file must have a ``# Projects``\nsection listing them as in the example\n\nAlso, remember to run ``build`` or ``serve`` commands from your Home\nDocumenation\u2019s **root folder** (in ``your_home_documentation/`` in the\nexample above) otherwise you may get errors saying ``metadocs`` can\u2019t\nfind a file.\n\nAdding a Python project\n-----------------------\n\n``metadocs`` comes with a useful ``autodoc`` command helping you easily\nadd a new python project to your documentation.\n\nAll you have to do is put the documented (Google-style docstrings) code\nalong the documentation in ``your_home_documentation/``. Say it\u2019s called\n``your_project_3``. Then you just need to make a new directory called\n``your_project_3`` go there, copy ``your_project_3``\\ \u2019s code in there\n(as a package, meaning it should include a ``__init__.py`` and use\n``autodoc``:\n\n::\n\n $ pwd\n /path_to_your_documentation/\n $ mkdir your_project_3\n $ cd your_project_3\n $ cp -r path/to/your_project_3 .\n $ ls\n your_project_3\n $ metadocs autodoc\n ... some prints\n $ ls\n Makefile source build your_project_3\n\nUnder the hood, ``metadocs autodoc`` runs ``sphinx-quickstart``, updates\ndefault values in ``conf.py``, runs ``sphinx-apidoc``, rearranges the\ncreated ``.rst`` files, builds the documentation with ``metadocs build``\nand updates the Home Documentation\u2019s ``index.md`` file to list\n``your_project_3``.\n\nIf ``metadocs autodoc``\\ \u2019s default values for the ``sphinx``\ndocumentation don\u2019t suit you, do update\n``/path_to_your_documentation/your_project_3/source/conf.py``.\n\nManual addition of a built documentation\n----------------------------------------\n\nIf you don\u2019t want to ``metadocs autodoc``, you may use any sphinx\nconfiguration you want. Just keep in mind that ``metadocs`` will run\n``make html`` from your project\u2019s directory (so check that this works)\nand ``metadocs serve`` expects to find a file called ``index.html`` in a\ndirectory called ``build/`` in your project.\n\nCustomization\n-------------\n\nYou may use any other theme for instance. To use ``mkdocs-nature`` just:\n\n::\n\n pip install mkdocs-nature\n\nThen change this in ``mkdocs.yaml`` : ``theme: nature`` and finally:\n\n::\n\n mkdocs build\n\nEdit the global configuration in ``mkdocs.yaml`` and each project\u2019s in\n``source/conf.py``.\n\nUseful Resources\n~~~~~~~~~~~~~~~~\n\n- `Mkdocs\u2019s Getting\n Started