Description
I was setting about generating the API documentation, but have a BIG problem, question!
At present we only have one site for the API documentation, namely http://www.htacg.org/tidy-html5/tidylib_api/, which is presently version 4.9.35.
We might keep that, but now it seems we have the need to add two or more sites, like -
- Documentation 4.9.35 - already done, but may need moving.
- Documentation 5.0.0
- Documentation 5.1.8
- Others, later, onward...
Obviously for the most part they will be the same but there are some important changes already, like say the two(2) new features 5.1.8 offers of --vertical-space auto, and --indent-with-tabs yes|no not present in 5.0.0.
So if I choose to download the 5.0.0 release/5.0.0 branch then I would like to refer to 5.0.0 API docs. And if I choose to go with a later stable release, say tag 5.1.8, then I want to be reading 5.1.8 API docs.
At first I thought of somehow combining them...
But since this documentation is generated using doxygen I do not think there is a way to sort of combine them together, like the reference for the vertical space API - http://www.htacg.org/tidy-html5/tidylib_api/quick_ref.html#vertical-space - be split into two parts - something like -
---------------------------------------------------------------------------
<h4>vertical-space 5.0.0</h4>
<tr><td>Type: Boolean</td></tr>
<tr><td>Default: no</td></tr>
<tr><td>Example: y/n, yes/no, t/f, true/false, 1/0</td></tr>
<tr><td>This option specifies if Tidy should add some empty lines for readability.</td></tr>
---------------------------------------------------------------------------
<h4>vertical-space 5.1.8</h4>
<tr><td>Type: AutoBool</td></tr>
<tr><td>Default: no</td></tr>
<tr><td>Example: auto, y/n, yes/no, t/f, true/false, 1/0</td></tr>
<tr><td>This option specifies if Tidy should add some extra empty lines for
readability. Default is 'no'. If set to 'auto', will eliminate nearly
all newline chars.</td></tr>
---------------------------------------------------------------------------
But that can not work, since the document generator, doxygen, must sort of have access to two branches in this case, release/5.0.0 and master, tag 5.1.8 at the same time to split it when the API have changed. No, that seems almost impossible...
My next idea is that the current http://www.htacg.org/tidy-html5/tidylib_api/ leads only to a version index, which directs into say sub-directories like -
<a href="http://www.htacg.org/tidy-html5/tidylib_api/4.9.35">Documentation 4.9.35</a><br>
<a href="http://www.htacg.org/tidy-html5/tidylib_api/5.0.0">Documentation 5.0.0</a><br>
<a href="http://www.htacg.org/tidy-html5/tidylib_api/5.1.8">Documentation 5.1.8</a><br>
... and so on ...
where each sub-directory is a full set of API docs for that version... each auto generated with the repo set at that version/branch/tag...
This would work, but I would really need help to set that up... at this time I only have a very vague idea about how yaml voodoo works to generate this site... and quite minimal understanding of doxygen generation...
But how do other projects, which have a changing API per version, do this?
Well it seems others like FLTK also separate it into a version index, and have a different URL per version -
FLTK 2.0 -> http://fltk.org/doc-2.0/html/
FLTK 1.3.3 -> http://fltk.org/doc-1.3/
FLTK 1.1.10 -> http://www.fltk.org/documentation.php/doc-1.1/toc.html
Likewise for CMAKE -
CMake 3.3.1 -> http://www.cmake.org/cmake/help/v3.3/
CMake 3.2.3 -> http://www.cmake.org/cmake/help/v3.2/
...
CMake 2.8.12 -> http://www.cmake.org/cmake/help/v2.8.12/cmake.html
So it seems there is a lots of precedence in using site sub-directories to hold each version... and that makes sense...
Once a particular version generation is done, and uploaded, it will stay like that forever... at least while that version is still available in distribution...
So that is sort of settled, use sub-directories for storage, unless others have other ideas...
But as already stated, I will really need BIG HELP with that...