Bugzilla – Bug 2196
Generate docset for usage in zeal/dash etc...
Last modified: 2020-02-24 18:43:42 EST
I like to use zeal (https://zealdocs.org/usage.html) which search engine is faster than the javascript based of the documentation (also allows for integration with 3rd party tools such as vim etc...). It needs a docset and apparently it should be easy to generate one for ns3. First reference to this is: https://groups.google.com/forum/#!searchin/ns-3-users/zeal/ns-3-users/kTVDMd2oPM8/K3lYq41qrxYJ I would like to assign this to myself
I generated a docset for Dash (see https://github.com/Kapeli/Dash-User-Contributions/pull/1096) which should also work for Zeal. Have fun!
reopen this until it is upstreamed to ns-3-dev
Hello, since this is not a patch for ns-3 itself and therefore won't get upstreamed, I suggest to close this issue none the less.
(In reply to Elias Rohrer from comment #3) > Hello, > since this is not a patch for ns-3 itself and therefore won't get > upstreamed, I suggest to close this issue none the less. Matt had agreed to write some project documentation (at the minimum, a HOWTO page in the wiki for how to generate the docset on your own, or how to get it as a third-party source online) so I'd like to leave open at least until that is done. I had some questions about whether more is needed: 1) any need to configure doxygen build in a special way to facilitate this? 2) do we have a Dash/Zeal maintainer who will keep the third-party sources up to date? If so, how are release versions managed?
(In reply to Tom Henderson from comment #4) > (In reply to Elias Rohrer from comment #3) > > Hello, > > since this is not a patch for ns-3 itself and therefore won't get > > upstreamed, I suggest to close this issue none the less. > > Matt had agreed to write some project documentation (at the minimum, a HOWTO > page in the wiki for how to generate the docset on your own, or how to get > it as a third-party source online) so I'd like to leave open at least until > that is done. > > I had some questions about whether more is needed: > > 1) any need to configure doxygen build in a special way to facilitate this? > Have a look at the README I provided: https://github.com/Kapeli/Dash-User-Contributions/tree/master/docsets/ns-3 It does cover how to generate the necessary step to reproduce the docset - feel free to copy it to the wiki if this would be sufficient. > 2) do we have a Dash/Zeal maintainer who will keep the third-party sources > up to date? I'll do that for now, even though I'm new to ns-3 itself and just created the docs for my own use in my learning phase ;) > If so, how are release versions managed? You mean how the versions are handled by Dash? I can provide different versions of a docset as a part of the docset.json file and Dash offers the capability to install multiple versions side-by-side.
Btw: I had to produce 16x16 and 32x32 versions of the ns-3 icon. I hope you are ok with the result and have no concerns regarding licensing asf.
weirdly enough I had not seen the updates and stumbled upon the docset randomly a few weeks ago. Thanks a lot for the docset. I love it.
Perhaps add a waf command to generate the docset? GCI project?
I doubt this is easily done. Actually, I don't know how docset generation would work in Linux environments. In macOS, the process still relies on an old tool ('docsetutil') formerly provided by Xcode, that since has been deprecated (see https://kapeli.com/docsets#doxygen). Btw. the updated docset for 3.30 is on my todo list and should be available soon.
SO on generating docset in Linux: https://stackoverflow.com/questions/32900458/how-to-make-docset-on-linux/35004788 To generate for dash (requires Go): https://github.com/technosophos/dashing#readme
(In reply to Peter Barnes from comment #10) > SO on generating docset in Linux: > https://stackoverflow.com/questions/32900458/how-to-make-docset-on-linux/ > 35004788 > > To generate for dash (requires Go): > https://github.com/technosophos/dashing#readme Thanks for the resources. I just realized that I already published the ns-3.30 docset. I assume the updates to ns-3.30.1 and ns-3.30.2 won't change anything substantial and are not worth the effort.
[Working through a GCI task submission] Creating a docket from Doxygen is done in two steps: 1. Run Doxygen with some different flags than we normally use 2. Run a Makefile generated by Doxygen The Makefile needs an Apple tool, docsetutils, which is no longer part of Xcode. This GitHub comment has the required components: https://github.com/Kapeli/Dash-User-Contributions/pull/1884#issuecomment-389793784 These need to be copied to /Applications/Xcode.app/Contents/Developer/usr/bin/ /Applications/Xcode.app/Contents/Frameworks/ /Applications/Xcode.app/Contents/SharedFrameworks/ This SO post says you don't need docsetutils, but that didn't work for me with Dash https://stackoverflow.com/questions/32900458/how-to-make-docset-on-linux/35004788 Alternative tools (which I couldn't get to work, or didn't try): https://github.com/technosophos/dashing#readme https://github.com/godbout/dash-docset-builder As Elias said, not obvious how to generate the docset on Linux...
GCI 2019 submission committed as f41076a78 In the end I installed Xcode-9.2, the last version which includes docsetutil. Build steps: sudo xcode-select -s /Applications/Xcode\ 9.2.app/Contents/Developer/ ./waf --docset sudo xcode-select -r This results in doc/ns-3.docset Future work: Generate a new docset as part of the release process, Submit to the Dash User Contributed Docsets. GitLab issue 154 https://gitlab.com/nsnam/ns-3-dev/issues/154