Process user's conf.py and index.rst through templates like the default version

[rkent]

I've been experimenting with rosdoc2 for the last month, because I want to make sure that I do proper documentation as I convert my robot to ros2. I have a lot of suggestions, but really the most import is to use templates with user content.

Currently, rosdoc2 can create a default conf.py and index.rst, and when it does so it uses python's format_map method with some template variables. Currently user-provided conf.py and index.rst do not have the same ability to use the template variables.

As a user, there are a few reasons why I want to have the same ability to use the template variables. The two main reasons are:

• I want to keep my documentation in-sync with the various things like package.version and package.description
• When I customize conf.py or index.rst, I want to start with a standard file, and possibly do minor changes to it.

In addition, if rosdoc2 is expanded to include more documentation beyond the current doxygen material, there are a lot more items that could be available in the template variables. In my demo, I've included:

• Links to the standard package documentation like README and LICENSE
• A link to index.ros.org, if it exists
• Links to soon-to-be-automatically-generated message format descriptions
• Links to documentation included in standard /doc folder

In PR #28 the template was expanded to include optional Python documentation. The same issue will be faced when msg, service, and action descriptions are added, so the available template variables are going to get more extensive.

The actual templating library is not important. I am not a fan of using python's format_map because it forces me to to do changes to python code away from the template variables to escape common constructs like {}. I should not have to mess with my code outside of adding the template variables in order to use the templating system. In my demo, I used jinja. But which one to use is not important.

My current demo is at https://github.com/rkent/rosdoc2/tree/index_links The default index.rst is included as a file rather than embedded in the code as index.j2

My demo package documentation can be seen here. It's a WIP though.

If this is an acceptable direction, I can submit some pull requests to implement.

[rkent]

This is going to be a pivotal issue for me to make progress with rosdoc2. I'll be doing a PR to suggest adding this feature, but let me show you where I want to go.

Below is the current version of the index.rst template from my experimental rosdoc2 repo branch. There are a lot of things that only are displayed if a package has certain features (like a /doc directory, or a python API for example). It is easier to see what is going on, and manage, this in template code than by piecing it together using python, or using the much less capable python .format_map method. But really a main motivation is that package developers should be able to keep their documentation in-sync with the package code directly, by including things like the package description or release from package.xml, rather than have to constantly edit an index.rst file.

.. GENERATED_CONTENT by rosdoc2.verbs.build.builders.SphinxBuilder.

{{ root_title }}
{{ root_title_underline }}

{{ package_description }}

{% if url_repository or url_website or url_bugtracker %}
Links
-----
{% if url_repository %}{{ url_repository }}{% endif %}
{% if url_website %}{{ url_website }}{% endif %}
{% if url_bugtracker %}{{ url_bugtracker }}{% endif %}

{% endif %} 
{% if meta_dependencies -%}
Dependencies of this Meta Package
---------------------------------------
{% for subproject in meta_dependencies -%}
* :doc:`{{subproject}}:index`
{% endfor -%}
{% endif -%}
{% if has_user_docs or extra_doc_files %}
Project Documentation
---------------------

.. toctree::
   :maxdepth: 2
   :glob:

   {% if '.' in doclist %}*{% endif %}
   {% if 'doc' in doclist %}doc/*{% endif %}
{% if extra_doc_files -%}
{% for (relpath, docname) in extra_doc_files %}
   {{ relpath }} <{{ docname }}>
{% endfor -%}
{% endif -%}
{% endif -%}
{% if has_standard_docs %}

Standard Documents
------------------
.. toctree::
   :maxdepth: 2
   :glob:

   generated/standards

{% endif -%}
{% if did_run_doxygen or has_python or has_msg_defs or has_srv_defs %}
Package API
-----------

.. toctree::
   :maxdepth: 4

   {% if has_python %}Python API <generated/python/modules>{% endif %}
   {% if did_run_doxygen %}C/C++ API <generated/cpp/index>{% endif %}
   {% if has_msg_defs %}generated/message_definitions{% endif %}
   {% if has_srv_defs %}generated/service_definitions{% endif %}

{% endif %}
.. toctree::
   :hidden:

   generated/index_and_search