Document incomplete? #32

Open
wh5a opened this Issue Jan 21, 2010 · 6 comments

Comments

Projects
None yet
4 participants

wh5a commented Jan 21, 2010

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.

Owner

thelema commented Jan 21, 2010

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?

wh5a commented Jan 22, 2010

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.

Owner

thelema commented Jul 6, 2010

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.

Contributor

mdekstrand commented Jul 6, 2010

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.

mdekstrand was assigned May 3, 2011

Owner

thelema commented Dec 28, 2011

https://github.com/MyLifeLabs/atd/blob/master/release.sh - Another project using git and building documentation on release

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment