The need to have an http server running to access the documentation of a personal project is — I would say — cumbersome.
It might be functional for a ‘systemic’ documentation, like a standard library, which, at least in my experience, is ‘naturally’ access on line (also being a part of larger ecosystem), and the addition of a mini-server, just providing the std docs only, would cover the remaining cases.
It seems to me quite less functional for a user-made library; and the variety of solutions proposed above is a hint that there is a problem.
Lets’ say I wrote a library, whoever will use it in his own projects will need to browse the documentation, possibly in the more streamlined way.
(Almost) all the libraries in other common languages (C, C++ or Java) I have used and use can be browsed directly (point you browser to its index.htmlet voilà!). I personally would end up skipping a library forcing me to install and run a specific piece of software in order to be read (unless it is the Holy Grail of the topic, which is not so common).
It is only me or someone else finds this peculiar too?
Nope, lets not drag this finished help topic down a tangent.
Moving this to a new topic.
It is easy to create a new topic and you can even link to other topics, specific posts, or copy a quote from some other topic. So please do that, instead of changing what the topic was about. (Helping somebody accomplish something specific)
I don’t really care what other languages do, you need a server running it, because browsers decided that running webassembly from a file resource is not allowed for some reason. I think that is the thing that should be questioned, if webassembly is supposed to be secure and sandboxed, then why can’t it be run from a file? That is what I find strange.
But I also don’t think it makes sense to argue about these trivial matters, unless you actually want to do something about it. Otherwise it just is pointless bike-shedding “lets do it like everyone else”, well no, lets not, the current documentation has made the implementation simpler without needing to replicate a whole bunch of logic in javascript.
If needing to run a webserver stops you from using the documentation, that seems silly.
I agree that it could be simpler to run the webserver and have it serve the documentation for a number of libraries, without repeated manual setups or having to craft customized build steps to run a browser (although if that is like 3 lines in the application it doesn’t seem that important to avoid that), but I think it is partly the community that should come up with something that smoothes out the rough edges and creates tooling for that.
The specific piece of software is a webserver, which isn’t some obscure unknown software, where you would have reasons for not wanting to run it.
firing up a webserver to local-host your docs via Python is just python -m http.server -b 127.0.0.1 [some-unused-port] -d [your-docs-dir]
if your code is on github, I found github pages to work well. For public libraries, public docs seem adequate to me, but of course you need to host this somewhere
In principle, you can build a webserver with Zig, so I was wondering if it would be possible to have that functionality via a zig command? E.g. zig docs run or similar?
right, the moment I posted the reply above I was thinking “wasn’t this possible with std already?” - but since one is always online these days, I just go to what is hosted on ziglang.org … anyways, that makes it seem like local-hosting lib docs via zig isn’t far away?
I was thinking it would be nice to offer the zig std workflow via a build step. So you could introduce zig build view-docs or something like that and have it basically do the same thing that zig std does but for your application’s documentation. Point being that you could observe doc comment changes via refreshing the page in the browser.
Of course, it would also let you make patches to the Zig autodocs wasm code and observe them immediately so that contributors could offer improvements to autodocs logic as well, testing those improvements for their own packages via the same mechanism.