Possibility to add documentation to index page #74

Closed
tomaz opened this Issue Mar 1, 2011 · 7 comments

Comments

Projects
None yet
2 participants
Owner

tomaz commented Mar 1, 2011

It would be nice to be able to insert arbitrary documentation to auto generated index page. This could be used for descriptions of framework (similar to how Apple does it for it's frameworks - for example foundation or AppKit).

This should reuse existing static documents. One way of implementing it would be to simply use specific file name pattern to identify insertion documentation; for example if any document template on any --include path would be named main-index-template or similar it would be used for insertion to generated index.html.

Another option would be to introduce additional cmd line switch identifying the document. This would be more explicit and probably less confusing.

This is (remotely) related to #68 and might be solved together.

A command line switch sounds good to me.

Owner

tomaz commented Mar 3, 2011

Implemented possibility of injecting descriptions to main index file. Closed by 7d18569.

Using --index-desc switch, you can pass the path to the file containing description that'll be injected in the auto generated index.html. The file can be formatted using the same rules as any other static document. The difference is it's not possible to link to it from other objects or documents (each generated object html already contains the link to main index and hierarchy). But it's possible to link any class or document from within the index description; the same logic is used for that as for any other source code comment or static document.

Online documentation will follow briefly... For now give it a try and let me know if there's anything else missing or something not working as expected.

Owner

tomaz commented Mar 3, 2011

Oh forgot it: you must use updated template files otherwise nothing will be seen in generated html!

That's great. Just got it installed now. It's really nice having everything generated through appledoc, with no external files to go and edit when I add a guide!

If in the future you do have a way of tagging included files specifically as companion guides, they could be included automatically (with the little table that Apple put them in). But this solution is a great improvement. Thanks :D

Owner

tomaz commented Mar 3, 2011

I'm currently working on at least partial implementation of this. It will only work for class, category or protocol comment for the start, see #68.

You could probably do tables using various Markdown extensions supported by Discount and reusing css classes used for creating specs for objects. But it's manual work, automated solution would require more involved approach and I'm currently short on time, so this will have to wait. At present I'm just closing bugs and possibly adding smaller features (such as mentioned #68). Feel free to add new issue though for future reference :)

Of course. That was just me being picky: this way meets all my desired functionality. I've got quite a nice workflow going where a script automatically runs appledoc and deploys the result on our intranet, and now with the current version I don't have to do anything else other than run it.

As far as being short of time goes, you've managed the quickest response to feedback I've ever seen in an open source project, so I'm very impressed :)

Owner

tomaz commented Mar 3, 2011

Thanks, I started the whole project after not being able to get decent documentation generator for Objective C (not to mention one with decent output :)) It's also a way of giving back to developer's community. I obviously can't implement every wish, but at least I can reply and comment. And if you find the tool helpful, make sure other developers hear about it; the more people using it, the greater the chance someone will pick up and help implement a feature, so we'll all benefit :)

@tonklon tonklon pushed a commit to tonklon/appledoc that referenced this issue Mar 8, 2012

@tomaz tomaz Implemented possibility of injecting descriptions to main index file. C…
…loses #74.

Using `--index-desc` switch, you can pass the path to the file containing description that'll be injected in the auto generated index.html. The file can be formatted using the same rules as any other static document. The difference is it's not possible to link to it from other objects or documents (each generated object html already contains the link to main index and hierarchy). But it's possible to link any class or document from within the index description; the same logic is used for that as for any other source code comment or static document.

Online documentation will follow briefly... For now give it a try and let me know if there's anything else missing or something not working as expected.
7d18569

This issue was closed.

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