When are you going to document this documentation tool? It's the third time
I see this on HN and I still can't tell how to use it or what to compare it to (what it is supposed to replace).
> ah sorry I missed this one. can you please let me know what do I need to add? I thought I have covered almost all topics and parts in order to be able to build a documentation. In other words, what you expect to see there?
As I said here already, I can't tell how to use it and what to use it for.
Let's assume I have a project that already has some code and no documentation.
First thing I want to know is what kind of artifacts your thing produces. This is important and there are several valid options, which include "HTML pages to publish on a generic web page", "HTML to be published on readthedocs", and "man pages".
Then I want to know how to start actually using the tool. Remember: I don't have any documentation structure and I know nothing about your tool. I don't know if it uses documenting comments (JavaDoc/Doxygen style), separate text files (SGML/asciidoc style), or maybe a combination of these (like Sphinx does). I don't know how to run your tool to generate the thing and how to control its output.
Then there is the issue of semantic markup. Any sensible documentation tool allows the writer to distinguish several important types of things, like functions, classes, and modules, and it does so in a single, designated way that results in always looking the same. I haven't seen anything like that in your tool, which means I, as an author, need to constantly remember how I mark the functions and modules.
You should compare how your documentation looks standing beside Doxygen, Sphinx, or much simpler asciidoc and POD (Perl's plain old documentation).