{"action":"created","issue":{"url":"https://api.github.com/repos/htacg/tidy-html5/issues/248","labels_url":"https://api.github.com/repos/htacg/tidy-html5/issues/248/labels{/name}","comments_url":"https://api.github.com/repos/htacg/tidy-html5/issues/248/comments","events_url":"https://api.github.com/repos/htacg/tidy-html5/issues/248/events","html_url":"https://github.com/htacg/tidy-html5/issues/248","id":105258281,"number":248,"title":"An API documentation question","user":{"login":"geoffmcl","id":1333435,"avatar_url":"https://avatars.githubusercontent.com/u/1333435?v=3","gravatar_id":"","url":"https://api.github.com/users/geoffmcl","html_url":"https://github.com/geoffmcl","followers_url":"https://api.github.com/users/geoffmcl/followers","following_url":"https://api.github.com/users/geoffmcl/following{/other_user}","gists_url":"https://api.github.com/users/geoffmcl/gists{/gist_id}","starred_url":"https://api.github.com/users/geoffmcl/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/geoffmcl/subscriptions","organizations_url":"https://api.github.com/users/geoffmcl/orgs","repos_url":"https://api.github.com/users/geoffmcl/repos","events_url":"https://api.github.com/users/geoffmcl/events{/privacy}","received_events_url":"https://api.github.com/users/geoffmcl/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/htacg/tidy-html5/labels/Docs","name":"Docs","color":"e102d8"}],"state":"open","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/htacg/tidy-html5/milestones/6","html_url":"https://github.com/htacg/tidy-html5/milestones/5.1","labels_url":"https://api.github.com/repos/htacg/tidy-html5/milestones/6/labels","id":1030807,"number":6,"title":"5.1","description":"Next release","creator":{"login":"geoffmcl","id":1333435,"avatar_url":"https://avatars.githubusercontent.com/u/1333435?v=3","gravatar_id":"","url":"https://api.github.com/users/geoffmcl","html_url":"https://github.com/geoffmcl","followers_url":"https://api.github.com/users/geoffmcl/followers","following_url":"https://api.github.com/users/geoffmcl/following{/other_user}","gists_url":"https://api.github.com/users/geoffmcl/gists{/gist_id}","starred_url":"https://api.github.com/users/geoffmcl/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/geoffmcl/subscriptions","organizations_url":"https://api.github.com/users/geoffmcl/orgs","repos_url":"https://api.github.com/users/geoffmcl/repos","events_url":"https://api.github.com/users/geoffmcl/events{/privacy}","received_events_url":"https://api.github.com/users/geoffmcl/received_events","type":"User","site_admin":false},"open_issues":8,"closed_issues":22,"state":"open","created_at":"2015-03-20T11:30:55Z","updated_at":"2015-09-12T13:40:40Z","due_on":"2015-09-20T22:00:00Z","closed_at":null},"comments":8,"created_at":"2015-09-07T19:07:31Z","updated_at":"2015-09-12T19:50:00Z","closed_at":null,"body":"I was setting about generating the API documentation, but have a **BIG** problem, question!\r\n\r\nAt 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.\r\n\r\nWe might keep that, but now it seems we have the need to add two or more sites, like -\r\n\r\n - Documentation 4.9.35 - already done, but may need moving.\r\n - Documentation 5.0.0\r\n - Documentation 5.1.8\r\n - Others, later, onward...\r\n \r\nObviously 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.\r\n\r\nSo 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.\r\n\r\nAt first I thought of somehow combining them...\r\n\r\nBut 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 -\r\n\r\n```\r\n  ---------------------------------------------------------------------------\r\n  <h4>vertical-space 5.0.0</h4>\r\n  <tr><td>Type: Boolean</td></tr>\r\n  <tr><td>Default: no</td></tr>\r\n  <tr><td>Example: y/n, yes/no, t/f, true/false, 1/0</td></tr>\r\n  <tr><td>This option specifies if Tidy should add some empty lines for readability.</td></tr>\r\n  ---------------------------------------------------------------------------\r\n  <h4>vertical-space 5.1.8</h4>\r\n  <tr><td>Type: AutoBool</td></tr>\r\n  <tr><td>Default: no</td></tr>\r\n  <tr><td>Example: auto, y/n, yes/no, t/f, true/false, 1/0</td></tr>\r\n  <tr><td>This option specifies if Tidy should add some extra empty lines for \r\n    readability. Default is 'no'. If set to 'auto', will eliminate nearly \r\n   all newline chars.</td></tr>\r\n  ---------------------------------------------------------------------------\r\n```\r\n\r\nBut 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...\r\n\r\nMy 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 -\r\n\r\n```\r\n<a href=\"http://www.htacg.org/tidy-html5/tidylib_api/4.9.35\">Documentation 4.9.35</a><br>\r\n<a href=\"http://www.htacg.org/tidy-html5/tidylib_api/5.0.0\">Documentation 5.0.0</a><br>\r\n<a href=\"http://www.htacg.org/tidy-html5/tidylib_api/5.1.8\">Documentation 5.1.8</a><br>\r\n... and so on ...\r\n```\r\n\r\nwhere 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...\r\n\r\nThis 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...\r\n\r\nBut how do other projects, which have a changing API per version, do this?\r\n\r\nWell it seems others like FLTK also separate it into a version index, and have a different URL per version -\r\n\r\n```\r\nFLTK 2.0 -> http://fltk.org/doc-2.0/html/\r\nFLTK 1.3.3 -> http://fltk.org/doc-1.3/\r\nFLTK 1.1.10 -> http://www.fltk.org/documentation.php/doc-1.1/toc.html\r\n```\r\n\r\nLikewise for CMAKE -\r\n\r\n```\r\nCMake 3.3.1 -> http://www.cmake.org/cmake/help/v3.3/\r\nCMake 3.2.3 -> http://www.cmake.org/cmake/help/v3.2/\r\n...\r\nCMake 2.8.12 -> http://www.cmake.org/cmake/help/v2.8.12/cmake.html\r\n```\r\n\r\nSo it seems there is a lots of precedence in using site sub-directories to hold each version... and that makes sense... \r\n\r\nOnce a particular version generation is done, and uploaded, it will stay like that forever... at least while that version is still available in distribution...\r\n\r\nSo that is sort of settled, use sub-directories for storage, unless others have other ideas...\r\n\r\nBut as already stated, I will really need **BIG HELP** with that...\r\n\r\n##### Anyone out there interested in helping with this side of the project?\r\n"},"comment":{"url":"https://api.github.com/repos/htacg/tidy-html5/issues/comments/139814224","html_url":"https://github.com/htacg/tidy-html5/issues/248#issuecomment-139814224","issue_url":"https://api.github.com/repos/htacg/tidy-html5/issues/248","id":139814224,"user":{"login":"pedromorgan","id":123932,"avatar_url":"https://avatars.githubusercontent.com/u/123932?v=3","gravatar_id":"","url":"https://api.github.com/users/pedromorgan","html_url":"https://github.com/pedromorgan","followers_url":"https://api.github.com/users/pedromorgan/followers","following_url":"https://api.github.com/users/pedromorgan/following{/other_user}","gists_url":"https://api.github.com/users/pedromorgan/gists{/gist_id}","starred_url":"https://api.github.com/users/pedromorgan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/pedromorgan/subscriptions","organizations_url":"https://api.github.com/users/pedromorgan/orgs","repos_url":"https://api.github.com/users/pedromorgan/repos","events_url":"https://api.github.com/users/pedromorgan/events{/privacy}","received_events_url":"https://api.github.com/users/pedromorgan/received_events","type":"User","site_admin":false},"created_at":"2015-09-12T19:50:00Z","updated_at":"2015-09-12T19:50:00Z","body":"Hi Denis...\nThe snag is that doxygen created the \"C api docs\"... and sphinx dont so\nthat,, well it does.. but c coders hate it.. so not an option... basically..\n\nI use readthedocs a lot, so understand, but for this project.. its doxygen..\nIf there was a \"readthedocX\".. then i would be pig in shit.. would run down\nthe street naked to the pub.... ;-))\n\n\n\n\nOn 12 September 2015 at 20:14, Denis Denisov <notifications@github.com>\nwrote:\n\n> readthedocs for me easier to make changes will be harder to anyone, but\n> it's up to you guys.\n>\n> —\n> Reply to this email directly or view it on GitHub\n> <https://github.com/htacg/tidy-html5/issues/248#issuecomment-139810398>.\n>\n"}}