move documentation within the source tree and hook into build

[anarcat]

there are great documentation tools out there, and lots of people around to contribute. the github wiki i would qualify as a "poor" documentation tool: the structure and organisation is very limited and it can be hard to navigate large sections (like the players handbook).

i would like to suggest moving that documentation into a doc/ subdirectory.

this would have the following advantages, the documentation:

• ... would be synchronised with the source code: when a new feature is implemented, the documentation can be updated in the same patch
• ... could be available online in the main UI (something which I feel is lacking right now)
• ... could be built automatically using standard tools like readthedocs.org, which have great themes which you can also adapt to your own

Even if the tools are not build with readthedocs.org, it would be nice to have a docs-wide, structured table of contents (and i don't mean the list of wiki pages, it's really hard to find your way in there). As things stand now, it's hard to expand on the existing documentation because of the above problems.

As a person often doing documentation, this would help me contribute. And I know it could help package maintainers in shipping the documentation along with the source code as well.

It is possible to merge the github wiki into the tree here, i'd be happy to help with that.

thanks for this great game!

[endless-sky]

A lot of modders never download the source, so the documentation has to be online somewhere. There might be a better place for that than the GitHub wiki, but the wiki at least has the advantage of being linked to directly from GitHub.

[anarcat]

Sure, of course the documentation would be online somewhere: in this very git repo. :) People would contribute through pull requests instead of wiki edits, but the workflow would be fairly similar... For example, taking an existing file like:

https://github.com/endless-sky/endless-sky/blob/master/data/alien%20effects.txt

... i can easily edit it through the github web interface by hitting the edit button...

[skyegallup]

The only improvement that I can see coming out of this is the ability for normal users to edit the documentation.

[DingusShingleton]

lehgogh commented 3 days ago
@ endless-sky Since we can't edit the wiki, could you add a bit of documentation for this in the "Creating outfits and weapons" page?

Seems like it would help you out at least :D

[skyegallup]

That's actually the only reason I added my previous comment on this issue.