Comments (16)
This would be fantastic!
from appledoc.
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.
from appledoc.
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.
from appledoc.
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.
from appledoc.
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.
from appledoc.
Started working on this. Will add basic functionality for the start then extend based on suggestions and wishes.
from appledoc.
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 :)
from appledoc.
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 :)
from appledoc.
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.
from appledoc.
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!
from appledoc.
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)?
from appledoc.
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 :)
from appledoc.
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.
from appledoc.
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 :)
from appledoc.
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!
from appledoc.
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.
from appledoc.
Related Issues (20)
- Crashed when a property with class Keyword HOT 5
- appledoc 只能生成第三方的的文档,自己写的类是没有包含在内 HOT 2
- links in methods HOT 1
- [email protected] HOT 1
- Apple Doc disabled HOT 2
- Apple
- Moha
- The method declaration line break
- The method declaration line break HOT 1
- AppleDoc DON't support @textblock or @code HOT 1
- How do I group functions? HOT 1
- cross references to instance method of other class HOT 1
- brew install appledoc not working
- Apple
- Build failed due to DDMinizip not found in CocoaPods HOT 3
- Me
- Code beginner HOT 1
- Hahah
- [GBEnumConstantData methodSelector]: unrecognized selector sent to instance
- Build input file cannot be found
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from appledoc.