Hello HN, we've posted here several times but today we're announcing that hdoc is becoming open source. Our goal is to make hdoc available to a broader set of developers. On top of that, we're hosting the deveopment of open source projects for free at hdoc.io.
Feel free to ask questions, we'll be answering as needed.
this macro will be treated as invalid syntax by many c++ parsers, including doxygen's I think.
I notice that hdoc is based on clang. I tried using clang to dump syntax tree of the above code snippet, the result was incomprehensible, because the macro has been expanded by the preprocessor.
hdoc uses Clang to parse your C++ code, so anything that Clang compiles should be fine. It's one of the benefits of using a production-quality parser instead of a homemade one like some other tools do.
I actually tried using clang -ast-dump to dump syntax tree of the above code snippet, the result was incomprehensible, because the macro has been expanded by the preprocessor.
The preprocessor will still be run prior to hdoc parsing your code, and the result should be valid assuming the your code is well-formed. C++ AST dumps are generally incomprehensible ;)
Please do try hdoc. The source is now available and there are precompiled binaries available on hdoc.io. It takes about 2 minutes to go from downloading hdoc to seeing your documentation on a website if you use the latter route.
We're looking at open sourcing hdoc in the future, and at least offering a free plan in the near term. We'd like to give back to the community too, it's part of the reason why we host our LLVM documentation freely.
We're currently targeting businesses and charging for the product understandably presents a barrier to many people, especially in C++ land where open source is the de facto standard. Unfortunately open source tools don't make money.
How would you like your documentation to be rendered when it's processed into markup formats? Source code documentation largely hasn't changed since the introduction of Doxygen-style comments so I'm curious to hear about your approaches.
I agree that bad documentation is often due to lack of effort. Many developers don't like writing documentation, which is unfortunate because bad documentation can drag down otherwise great projects. If I'm evaluating two libraries and one has great docs and the other has awful docs, you know which one I'm picking.
Likewise, hdoc isn't instantly going to make an engineer spring up and say "I'm going to write documentation!". No tool is going to do that. hdoc is meant to simplify and streamline the process of writing documentation. Current tools disincentivize writing documentation. If you need to spend a day cobbling together 5 different tools and themes to set up a documentation page for your project you might not be as eager to do it as you would be if you could write a five line configuration file and run a single binary.
No doubt there are free tools that can produce decent output. However, all of them require considerable effort that could be spent writing code or documentation. Others don't support modern features, or completely fail to process basic C++ code. Clearly a market for a tool which solves these problems exists, there is no shortage of people asking about Doxygen alternatives or better ways to document their C++ code. Lastly, there are companies in other communities which provide a similar services, for instance ReadTheDocs.com which has documentation and managed hosting for Python projects.
ReadTheDocs.com is largely the de-facto standard for Python projects because it is free to use. Since a lot of developers have experience with it, in production too, it is often used as a host (even though it is sub-par as a web-host and CI service). For a product which seems to have been trademarked in 2019, not having a free-plan or more importantly, one for FOSS projects, means this is at best, a niche option. Additionally, being proprietary and closed source means it will be difficult to integrate into multi-language programs. Doxygen is a good standard, which works across multiple languages, and its reach is augmented by Sphinx with inter-sphinx. In the domain I work (scientific software), very few tools are written in pure C++.
By the way, I hope my comments are not taken as anything other than constructive criticism.
LLVM/Clang are generally well-documented but there are places that don’t have great coverage.
Unfortunately tools are only part of the solution. Our goal with hdoc is to make writing documentation easier and to make it easier to create great/cohesive output. If engineers perceive writing documentation as too laborious they’ll be unlikely to do it, so we hope that hdoc’s workflow and results help.
Yes, this is one of the many improvements we plan on adding soon. It was cut from the MVP because we wanted to ensure that it was 100% accurate. Complex code bases can be ambiguous and it would be a disservice if the user clicked on one of these crosslinks and it took them to the wrong symbol.
When we originally implemented the Doxygen command support we looked at the most used commands in the code bases we profiled, and settled on about five, which we cut down to those three. Support for more commands is on the roadmap as we look to cover more of the Doxygen spec. This is a reasonable thing to have that many people would find useful, we just didn’t focus on it for the MVP.
C++ is falling behind in the quality of documentation output compared to what tools like rustdoc, ReadTheDocs, and godoc generate.
Getting good output from existing C++ tools requires disproportionate effort that could be better spent elsewhere.
Furthermore, existing tools have a hard time dealing with modern C++.
We made hdoc to solve these problems: prioritizing the quality of output, making the developer experience seamless, and retaining compatibility with existing best practices.
hdoc lets you generate reference API documentation and put supporting guides, tutorials, how-tos right alongside your other docs.
We have a sample of what hdoc's output for LLVM+Clang: https://docs.hdoc.io/hdoc/llvm-project/.
The source for the repo is available here: https://github.com/hdoc/llvm-project/
Use the code HDOC-HN-LAUNCH for your first three months free when you sign up. 5 codes are available.
More or less a modern replacement of Doxygen. The goal is to make writing good documentation easy. To accomplish that we've incorporated Markdown pages alongside the documentation, a modern and lightweight theme, Algolia-style search, minimal configuration, and simple deployment/CI integration.
Spent the second half of last year in alpha, putting the finishing touches on the release candidate now and hope to release this month.
The hdoc alpha release is now available on Linux and we're looking for feedback from users. If you're interested in a better documentation tool for C++, please consider trying out the alpha.
Feel free to ask questions, we'll be answering as needed.