This is the first step toward addressing #42. I addressed some of the reasoning there, but let me restate it.
First, the internal templates that are currently used with format_map automatically include various information from the package, such as the package name and version. I want to add additional useful information from package.xml as well, such as the description, urls, and meta-package subpackage list. Currently, if a user decides to customize one of the required files (conf.py, index.rst, or Doxyfile) they should have the same capability as rosdoc2 to automatically include package information.
Second, it is not easy to see what index.rst is supposed to look like with the current method of assembling it from python code. The file index.rst.jinja is (at least to me) much easier to understand and modify than the current code. There are reasons that web platforms use templates and not raw code to generate website layouts.
This PR is a first step, designed as a refactor that does not change the external appearance. In particular, a user-provided index.rst.jinja is not yet supported. But that will be added in followup PRs. The goal will be that the package author could include either an index.rst or an index.rst.jinja, and either would be supported. The same support will be added for conf.py and Doxyfile as well. If the user wants to customize their index.rst, they will simply have to copy index.rst.jinja to the ./doc directory, and it will be automatically used.
Of course this all needs to be documented as well for the package author to take advantage of it. That will be done once we have agreed on the overall concept.
This is the first step toward addressing #42. I addressed some of the reasoning there, but let me restate it.
First, the internal templates that are currently used with format_map automatically include various information from the package, such as the package name and version. I want to add additional useful information from package.xml as well, such as the description, urls, and meta-package subpackage list. Currently, if a user decides to customize one of the required files (conf.py, index.rst, or Doxyfile) they should have the same capability as rosdoc2 to automatically include package information.
Second, it is not easy to see what index.rst is supposed to look like with the current method of assembling it from python code. The file index.rst.jinja is (at least to me) much easier to understand and modify than the current code. There are reasons that web platforms use templates and not raw code to generate website layouts.
This PR is a first step, designed as a refactor that does not change the external appearance. In particular, a user-provided index.rst.jinja is not yet supported. But that will be added in followup PRs. The goal will be that the package author could include either an index.rst or an index.rst.jinja, and either would be supported. The same support will be added for conf.py and Doxyfile as well. If the user wants to customize their index.rst, they will simply have to copy index.rst.jinja to the ./doc directory, and it will be automatically used.
Of course this all needs to be documented as well for the package author to take advantage of it. That will be done once we have agreed on the overall concept.