===============================
 xNVMe Documentation Generator
===============================

This repository contains the technical documentation for xNVMe_ which is live
at `https://xnvme.io <https://xnvme.io/>`_, hosted on GitHUB-Pages_, with the
statically generated content stored in
`https://github.com/xnvme/xnvme.github.io <https://github.com/xnvme/xnvme.github.io>`_.

The documentation lives in ``docs/`` and consists of a manually written text
formatted as reStructuredText_ in a SphinxDoc_ project. In addition to the
hand-crafted text, then a bunch of things are auto-generated by inspecting the
xNVMe headers, command-line tools, usage examples and installation procedures.

The autogenerated part is produced by the following tools:

* SphinxDocBuilder_ produces HTML for human consumption based on the ``.rst``
  files in 'docs', this is the actual documentation including the
  auto-generated API-docs, output from command-line tools as generated by kmdo_
* Doxygen_ parses the xNVMe source autodoc-comments into XML
* Breathe_, a SphinxDoc_ extension enabling the use of Doxygen_ in SphinxDoc_
* Python_ for the scripts in ``toolbox/`` and ``docs/autogen/``, primarily the
  API-generator: ``toolbox/apigen.py``. The API-generator consumes the output
  from ``excuberant-ctags`` to generate ``.rst`` to the included in the
  SphinxDoc_
  and refer to the entities generated by Breathe_
* kmdo_ produces output from commands / usage examples for SphinxDoc_
* git_ retrieves the xNVMe_ source via a git-submodule
* make_ for convenient instrumentation of the various tools described above,
  the ``Makefile`` is the glue-code bringing it all together.

  - ``make doxy`` invokes ``doxygen`` and parses the xNVMe source-code for
    Breathe_ to consume

  - ``make apis`` invoke the Python script emitting ``.rst`` to be used by
    SphinxDoc_

  - ``make sphinx`` invokes the SphinxDocBuilder_ builder, producing the documentation
    based on the current state of the documentation in ``docs/``

  - ``make docs`` invokes a couple of pre-curser targets cleaning up previous
    build, installing dependencies, setting up the buildir then invoke the four
    make-targets above

  - ``make commands`` invokes kmdo_ producing the command-output from the
    various command-line tools and examples, note that this is somewhat
    volatile as the various cli-examples do destructive things. Thus, to avoid
    accidents then ``make commands`` is not invoked as part of ``make docs``.
    ``make commands`` should be invoked in a safe environment such as a
    qemu-guest. For details on this, then have a look at the GitHUB Action
    workflow, it instantiates a qemu guest with an emulated NVMe device, and
    executes the commands inside of it.

Usage
-----

Edit the files in ``docs/`` as you see fit, then run::

  make docs

This will generate the **HTML** which you can see by opening
``builddir/html/index.html`` or by invoking::

  make docs-view-html

Automation
----------

This is a todo-task, this should be happening automatically when tags are
pushed to xNVMe_ and it would also be nice to have it generated for the
``next`` branch and for the ``dev`` branch, providing documentation preview or
work-in-progress.

* GitHUB-Actions_, ...
* cijoe_, ...
* qemu_, ...

.. _Breathe: https://breathe.readthedocs.io/
.. _Doxygen: http://www.doxygen.nl/
.. _GitHUB-Pages: https://pages.github.com/
.. _Python: https://www.python.org/
.. _SphinxDoc: http://www.sphinx-doc.org/
.. _SphinxDocBuilder: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
.. _git: https://git-scm.com/
.. _kmdo: https://pypi.org/project/kmdo/
.. _make: https://www.gnu.org/software/make/manual/make.html
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _xNVMe: https://github.com/OpenMPDK/xNVMe/
