Possibility to add arbitrary documentation such as main page

[tomaz]

This would not be attached to any class, category or protocol. It should prefferably be completely decoupled from source files - as a set of "external" files created outside picked up by appledoc and copied to output directory.

Ideally, this should be somewhat processed by appledoc for cross references and use the same markdown syntax.

Additionally, there should be a way to link to this static documentation from within standard source code comments. It would also be nice to have it linked as companion guide so that it would also get listed in doc set.

[ghost]

This would be fantastic!

[CarterA]

I'm going to put my vote in for this as well. It'd be great to be able to create "Programming Guides" for my libraries, as Apple does with theirs. The guides can then by linked to from class documentation, whenever there is something that requires extra detail.

[seeker12]

I love this idea. I often would like more detailed description of where a method fits in the context of the envisioned application workflow. In the development process, implementation of how to support that workflow changes often. I prefer to document methods and properties with succinct comments. So it would be great to be able to link to additional descriptive "external" content that could be maintained separately. I see this as potentially quite useful for a small team of developers to keep informed of functional aspects of their APIs and their expectations of how they integrate.

[amyworrall]

I'd also like this. In the current library I'm writing, I need to document a file format. It'd be great if I could write some markdown or something, and appledoc would handle cross-references and CSS styling it up right, and then add it to the main page.

[tomaz]

I'm also thinking in the same direction - have a set of markdown formatted files which can be included through command line switch (for example --include <path> where path can be either a concrete file or directory with a bunch of files). Then it's open where the files would reside on the disk (I guess in most cases these are project specific, so it would make sense to include them near source files, most likely included in the same repository). All such files would then be processed by appledoc for any cross references and formatting, so the same commenting style can be used.

This should also support arbitrary content, such as images, videos and similar. This can probably be handled with html tags directly (need to make sure code is not escaped). It's also probably a good idea to somehow allow custom stylesheets, although this seems more complicated or would require additional @ directive.

More ideas welcome.

[tomaz]

Started working on this. Will add basic functionality for the start then extend based on suggestions and wishes.

[amyworrall]

Awesome. Just thought I'd let you know I really appreciate what you're doing. My current task at work is to write an API and present the documentation, before I get on with coding. The documentation currently looks so much more awesome than the doxygen stuff ever did :)

[tomaz]

Implemented possibility to add arbitrary documentation. Closed by 97db241.

This was one of much requested features. It allows adding arbitrary files to generated documentation. It's enabled with one or more --include switches. All files and directories specified are simply copied to docs subfolder within generated HTML files. So basically, you're free to write any HTML or whatever you want included with the generated documentation.

But the power lies in special "template" files. These are just normal text files which names end with -template (for example document1-template.html). Extension of these files is not important - they will always be converted to .html! The files can reside on any subpath - the path will be preserved. All such files are processed using the same logic as any other comment, so you can use appledoc comment syntax, including cross referencing any object or member. You can also cross reference these files from "normal" comments (or other documents) by simply writing the filename without -template and extension. You don't have to deal with subpaths either, these will be automatically picked up for you! Online documentation is not yet updated, will do it shortly.

At this point, it's basic stuff only. As such it has much potential for future (like adding markdown syntax for headings, images and similar - for now just use HTML tags). But at least it's a start and get's work done for the moment.

Enjoy and let me know if you find something not working as expected :)

[CarterA]

Have you considered using another library for Markdown parsing? I'd like to be able to use the full power of the language. Discount would probably work quite well.

[tomaz]

Actually I was looking into possible markdown parsers at the time I was investigating comments processing. Discount seemed like most suitable due to being implemented in C. I gave it some time but then decided it was too involved for what I wanted to have. One of the main reasons were cross references, @ directives, and integrating with template engine (at present every aspect of final HTML is completely redesignable just by changing template file, no recompiling necessary) to name just a few.

On the other hand, static documents require more in depth options, so I agree with you. Will reinvestigate possibility. I opened another issue for this - #66. Feel free to add comments and suggestions there!

[amyworrall]

I'm just experimenting with the new feature. It's certainly a better workflow than what I was using before.

Is there any way to add links to the documents from the main page? So as well as columns for Classes and Protocols, we have "Guides" (or whatever)?

[tomaz]

You can cross reference static documents the same way as any other documented object. It's described in online documentation. See also #66 for full Markdown support as you're likely use that on static documents.

I'm also planning to add all static documents included through @see directives inside class, category or protocol comment as companion guide inside the object specifications at the top of it's page - see #68.

Hope this answers your questions, otherwise feel free to ask again :)

[amyworrall]

Thanks ever so much for the quick reply! I really like appledoc, and the great support make me like it even more. I have indeed noted the markdown support, and that will save me a lot of time in the future.

I'll briefly explain my workflow so you can see why I'm making this request. I'm writing a framework called WSKit, and I have a script set up to publish the documentation directly onto our intranet. The index.html file (the autogenerated one that has the list of classes) is where anyone who wants to know about WSKit looks: it's linked to from the intranet homepage.

The stuff I'm including in separate files with --include is things like a getting started guide, and a guide to the data file format. A getting started guide isn't really related to any one specific class: it should be accessible to anyone who wants to browse the documentation.

I could always write my own index file, linking to my guides and the rest of the appledoc-generated documentation, but that would be the only manually generated file in the whole thing. I'd much rather appledoc showed links to the guides on index.html.

[tomaz]

I think I understand now (hopefully) :) One way of doing this would be to allow adding arbitrary description to the index file itself (like Apple does it for Foundation or AppKit frameworks). Would that work? Let me know and I'll open a new issue (or you can open it yourself :)

[amyworrall]

That would work. I'd marginally rather it listed all the guides automatically, but being able to add a description would be a lot better than my current method.

Thanks very much for your hard work!

[tomaz]

That would also be possible although it would require marking a document as a "guide" in some way (perhaps the simplest just following some file name pattern like name-guide-template.html). For the start just adding possibility of inserting documentation to index page should do and we can then extend it. I've created new issue - see #74.