geshi-1.0
geshi-1.0 copied to clipboard
GeSHi
update the documentation
This was discussed earlier in #77 and #78 - I'm moving the discussion to it's own ticket.
Currently the documentation that comes with GeSHi is quite outdated and hard to maintain. Here's what I suggest:
Remove src/docs/api completely from the repository and instead autogenerate it on push to master using travis and push it to either github pages or into the github wiki (with a note that the api docs are autogenerated and should not be edited).
Remove src/docs/geshi-doc* from the repository and instead move it to the wiki, giving the community a chance to keep it updated.
Move the rest of the src/docs folder out of the src, since it is not sources - some of the files are also quite outdated and it might be an idea to just delete them completely.
For completion, I quote the previous discussion with @cweiske here:
I'm not sure if I want [...] moving docs out of the repository. API docs can be dropped (because they can be autogenerated), but usage and so should stay in the repository itself. geshi has seen CVS, SVN and now git on github, and I guess that github will not be the last place it lives. Having the docs outside the repository makes moving to the next system harder.
The current document is a hard to maintain HTML file that seems not to have been touched significantly in the last 10 years. Moving it to the github wiki makes it easier to edit (because markdown) and opens it for easy additions by users. Wiki contents can easily be checked out via git (https://github.com/GeSHi/geshi-1.0.wiki.git) so you're not risking that documentation is siloed into github should you wish to migrate to a different service later on.
If you insist on keeping it in the source I would at least recommend splitting it into multiple files and maintain it in markdown format. HTML could then produced alongside the API doc generation.
One more thing: I created wiki pages from the current documentation a few days ago. Should the maintainers decide that the documentation should not be split off the sources, the wiki pages should be deleted and the wiki be closed for the project.
How about moving documentation out of src directory but keeping it in the repository?
Converting documentation into Markdown format sound like a good idea.
What do the maintainers think? Let me know if I can help. 😄
- moving out of src into doc/ is a good idea
- converting from html is a good idea
- markdown is not such a good idea, I prefer rST.
If you want to provide a patch for this - go on.
I spent a couple of hours converting and fixing up the document for markdown already. The result is in the wiki. Feel free to redo it in rST or convert the markdown to it or whatever. I won't spend more time on it.
The geshi-doc.html file will stay for now unless someone provides a patch that enables us to build the big html file from small, managable markdown/rST files. The wiki as @splitbrain converted it will stay until then.