Bug 2196 - Generate docset for usage in zeal/dash etc...
Generate docset for usage in zeal/dash etc...
Status: RESOLVED FIXED
Product: ns-3
Classification: Unclassified
Component: documentation
pre-release
PC All
: P5 enhancement
Assigned To: Matthieu Coudron
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2015-10-19 10:09 EDT by Matthieu Coudron
Modified: 2020-02-24 18:43 EST (History)
4 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Matthieu Coudron 2015-10-19 10:09:29 EDT
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
Comment 1 Elias Rohrer 2016-09-27 08:44:55 EDT
I generated a docset for Dash (see https://github.com/Kapeli/Dash-User-Contributions/pull/1096) which should also work for Zeal. 

Have fun!
Comment 2 Tom Henderson 2016-09-27 10:00:44 EDT
reopen this until it is upstreamed to ns-3-dev
Comment 3 Elias Rohrer 2016-09-27 10:15:54 EDT
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.
Comment 4 Tom Henderson 2016-09-27 12:53:13 EDT
(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?
Comment 5 Elias Rohrer 2016-09-27 13:17:36 EDT
(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.
Comment 6 Elias Rohrer 2016-09-27 13:20:35 EDT
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.
Comment 7 Matthieu Coudron 2019-06-24 01:10:33 EDT
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.
Comment 8 Peter Barnes 2019-11-05 18:58:35 EST
Perhaps add a waf command to generate the docset?

GCI project?
Comment 9 Elias Rohrer 2019-11-06 03:31:23 EST
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.
Comment 10 Peter Barnes 2019-11-06 04:26:53 EST
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
Comment 11 Elias Rohrer 2019-11-07 10:14:06 EST
(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.
Comment 12 Peter Barnes 2020-02-05 17:08:25 EST
[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...
Comment 13 Peter Barnes 2020-02-24 18:43:42 EST
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