Move documentation from github wiki pages into the repository itself

[ohm314]

While I'm liking opengrok more and more I find the documentation could need some work. There are many small typos and a number of points that could use clarification and improvements. I'd love to help with this as I'm putting time and effort into figuring out how to setup opengrok at my lab. Currently documentation is sitting in the github wiki and I don't see a way how someone, who is not part of the dev team, could suggest changes/fixes to the documentation. So, I wanted to ask if the documentation could be moved into a top-level directory docs/ of the repository. There are different approaches one could take:

1. Simply store the wiki pages as a bunch of .md files. One needs to update crosslinks accordingly, but that should be fairly easy
2. One could also go for a more involved solution and move to sphinx documentat. One would need to reformat the documetation into rst, add the necessary build scripts and publish them on readthedocs

Maybe for starters going with option 1 would already be a big improvement. Besides improving the documentation itself, this would allow the community to be more involved. I would certainly volunteer to help with this if the developers are open to accepting such a change.

[ahornace]

I personally kind of like how the GitHub wiki works. What about cloning https://github.com/oracle/opengrok.wiki.git, making the changes and opening a new issue with the diff? That way it's almost the same as having a PR (just except the click of a button the changes would have to be applied by a maintainer).

[vladak]

I personally kind of like how the GitHub wiki works. What about cloning https://github.com/oracle/opengrok.wiki.git, making the changes and opening a new issue with the diff? That way it's almost the same as having a PR (just except the click of a button the changes would have to be applied by a maintainer).

Too bad there is no PR workflow on Github for wikis as I think that would be welcome by many projects. Let me try to reach out to Github Support to consider this.

[vladak]

Filed a personal ticket to track this.

[ohm314]

Thanks for looking into this. It will be interesting to know if such a feature is on github's roadmap, but in any case I wouldn't expect this to be available any time soon. The "diff in issue" solution reminds me too much of sending emails with patches 😄 but as a stopgap it would work of course. I still think a readthedocs based documentation would be much nicer? @vladak , I don't think anyone can access your ticket, so please share their response once you get it.