GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
I gave the recently release 1.0 a try. It seems that a lot of documents available in the prior release have gone missing. For example, I cannot find any information about the syntax extensions now. And #man cannot find anything useful. The reason seems to be that the html/api/*.idex files are missing.
Yes, the documentation isn't as complete as before - it's become a simple API documentation. I want to extend it, but am unsure about how best to do this.
As to the issue of #man, most of the .idex files were generated by the old documentation generation scheme. I'm open to generating them again, but not to having a 15-minute documentation generation phase. Any suggestions?
I don't know, maybe create another make target for generating complete doc? Or you can host the doc somewhere (like on github) to save users some build time.
Why not have a make target for generating the index files, but include pre-generated files refreshed at every version tag in the release tarballs. Then if one's building a release, the .idex files are already there. If one's building from git, one can rely on the pre-generated, perhaps somewhat obsolete indexes, or one can manually target them to re-generate.
If you're willing to put some work into this, it's doable. I won't check documentation into git, but it can be put into release tarballs if needed. Of course it'd have to be done automatically.
Including the index in release tarballs but generating it when building from git tarballs sounds reasonable to me. This is the approach taken by GTK+ for things like their symbol definition files, I believe. It will require the release generation process to be somewhat more sophisticated than just git archive, but doable.
https://github.com/MyLifeLabs/atd/blob/master/release.sh - Another project using git and building documentation on release