I used pegdown-doclet for this for a long time. It made documentation in code as easy to read as the generated docs. I don’t think most developers knew that JavaDoc was HTML to begin with (or evernlooked at the rendered docs).
You can embed doc generated by other tools in a Docusaurus site, as a plain page or an iframe. Some people embed Javadoc, OpenAPI or Redoc in Docusaurus.
You can also generate md to make that doc native. I've seen people generating docs from a GraphQL schema for example
Sounds intriguing. Building beautiful docs is a super important and challenging tasks, especially for
open-source dev tools!
I currently use Mkdocs Material but I spent days customizing it for better appearance!
Give me local HTML files I can stash in my filesystem.
Apparently devdocs does have an API to download docsets. I just installed the Emacs package that someone recommended in another thread and it let me download the docs.
Hah! I was working on something almost exactly like this as a personal project.
Wonder how they did the doc/pdf creation? I thought about using LaTeX, and there are (commercial) html renderers, but I was trying to keep it cheap and easy.
I've the same experience. Soem years ago I tried DocBook to render HTML and PDF documents, but the whole setup was so unpleasant that I gave up. Writing the syntax is not overly hard, but also not pleasant. I ended up with AsciiDoc, what is nice to read and write and which has a rich set of features. It is also very easy to set up: just download AsciiDoctor and you're ready to go. https://asciidoctor.org/
I find that the best way to build docs is to use some sort of a static html generator and host the html yourself, which is not at all hard to do. There are free and open source themes available to host your own docs in various site generators.
My personal favorite is hugo. Previously I have built a documentation for a large project [0] using hugo and it gave us 100% control over how we design or host it. Outsourcing a doc to a SaaS seems like something I would never do if I cared about the product/software.
Well what I liked about Mobiledoc-kit[1] is that their demo was essentially an explanation of their document model. You changed things on the left, then saw the document model mutate in real time, and finally saw the rendered output.
Also, the very first thing in their documentation is an explanation of how to write a 'card' for embedded input, which is what is used to embed images in the demo.
It was an ah-ha! moment for me because most editor documentation begins by telling you how they parse ranges, and showing you how you can use regex to back-check to document and change it to your own elements, etc. That's just too deep into the internals for me to get an idea of what's going on.
So true! I've also discovered for myself that keeping a one-page document, serving as red thread makes everything so much easier.
However at some point I wasn't satisfied with the options a regular REAMDE offers. I wanted to write such a document in a declarative style and eliminate the limitation of having just HTML as an output format. Luckily a friend of mine is working on a parser that reads markup (using as much natural language as possibe, inspired by Markdown et. al) and turns it into a data representation (JSON) rather than pre-rendered HTML.
So it's just the front-end, relying on you to manually write all the HTML. I'd love some software to make generating these (or similar) annotated documents easily. Any ideas?
Yes. Thank you. I like POD for man-page -style docs, but for longer multi-section docs I'm not sure it buys you much more than plain text (except that you can easily convert to other formats). Also, it's harder to read than plain text -- though maybe easier than docbook xml.
The POD docs I see as html are just single long html pages. I realize this is just an implementation issue though.
Nice project! What was the main reason to build your own docs framework? Why didn't you go with ReadTheDocs or some other widely used tool?
Some nitpicks:
1. It would be nice to have an easy way to link to a specific (sub)section. I see the heading IDs are already there, so maybe just add some small anchor icons like [1]? Also, it might be good to change the anchor in the addressbar when clicking a side menu item.
2. It doesn't work without JS. I know it's common with a lot of websites today, but software docs may be the thing people sometimes need to view in a console browser with 80×24 resolution when the shit hits the fan… EDIT: I see you have a way for server-side render described in your Readme, that's great. :)
3. The print stylesheet could use some tweaking. Eg. these "Author Demo Github" links take up a relatively large space and they are pretty much useless on paper. Same with the menu heading and hamburger icon. [2] The links are even overlapping the content on some pages. [3] I don't know how often people print out documentation, but it might be a pretty common use case.
I made it because I like to write nice documentation for my projects but I was tired of docbook. I love markdown too :)
I thought of making a github webhook to automatically generate gh-pages using it but moved on another project in the meantime.
I like your idea of documentation as a service and I think you have something great with DocumentUp. We can definitively see if we can do something together. I'm deep in another project for the next two weeks (at least) but we can chat on gtalk (maxime.bouroumeau@gmail.com - I'm in GMT+1) if you want, to see what we could do in the future.
reply