New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Possibility to add documentation to index page #74

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

Comments

Projects
None yet
2 participants
@tomaz
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.

@amyworrall

This comment has been minimized.

amyworrall commented Mar 1, 2011

A command line switch sounds good to me.

@tomaz

This comment has been minimized.

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.

@tomaz

This comment has been minimized.

Owner

tomaz commented Mar 3, 2011

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

@amyworrall

This comment has been minimized.

amyworrall commented Mar 3, 2011

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

@tomaz

This comment has been minimized.

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 :)

@amyworrall

This comment has been minimized.

amyworrall commented Mar 3, 2011

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 :)

@tomaz

This comment has been minimized.

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 pushed a commit to tonklon/appledoc that referenced this issue Mar 8, 2012

Implemented possibility of injecting descriptions to main index file. C…
…loses tomaz#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.

This issue was closed.

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