Generate and publish doxygen output automatically

We should have a cron job or a jenkins process or something that runs "doxygen" in our codebase and publishes it at some official location.

changed milestone to %Tor: 0.4.3.x-final

Trac:
Parent Ticket: #29214 (moved)

added component::core tor/tor milestone::Tor: 0.4.3.x-final network-team-roadmap-november parent::29214 priority::medium resolution::implemented s31-docs severity::normal sponsor::31-can status::closed type::task labels

• We build it automatically, cf. https://jenkins.torproject.org/job/tor-doxygen/
• Still to do: set up a static component, the corresponding web stuff, and figure out pushing.

Trac:
Cc: nickm to nickm, weasel

Did we arrive at a (domain) name we want to use for this?

Also let us know if you want the doxygen tree to be at /, or if you want some directory structure (like /tor/master or something). We can redirect from / to that directory for now if we want.

Trac:
Cc: nickm, weasel to nickm, weasel, gaba

I suggested docs.torproject.org/tor, which sparked the following discussion:

---

<+weasel> pili: having it be in a subdirectory of something that gets built somehow makes it significantly more different [17:43:30] <+weasel> so, how will you built your thing and where and how does doxygen come into it? [17:48:00] <+pili> well, this is the problem, we're not yet at a place where we have started thinking about these things [17:48:41] <+pili> I don't think it's going to be a lektor like thing though [17:48:56] <+pili> as in, it's not going to be the same sort of thing as the current portals [17:49:13] <+weasel> is docs for all kind of docs, or for development stuff? [17:50:21] <+pili> docs for development stuff [17:50:42] <+pili> so developer portal will hold information about all the teams and their projects [17:51:05] <+pili> and it will have links to the docs for the different products/projects, hosted on the docs portal [17:51:10] <+weasel> weird that developer stuff lives at docs. [17:51:12] <+weasel> but ok [17:51:22] <+weasel> so how about we just put the doxygen build at https://tor.docs.torproject.org/? [17:51:45] <+weasel> or src-ref.docs.torproject.org [17:51:52] <+weasel> or src-ref.docs.torproject.org/tor/master? [17:52:32] <+pili> https://tor.docs.torproject.org/ wfm for now, with the caveat that at some point we'll want to think about the information architecture for this properly and might need to move/change it... [17:52:46] <+pili> and it also depends on how many other docs there are for tor that we will want to host there [17:53:28] <+pili> can someone remind me where this currently lives so I can see the sort of docs these are? [17:53:41] <+weasel> https://people.torproject.org/~nickm/tor-auto/doxygen/ [17:56:38] <+pili> ok, so not the man page for example, how would that fit in to this naming scheme if we wanted to add it to docs.tpo under core0tor somehow... [17:56:39] <+pili> ? [17:56:54] <+pili> s/core-tor [17:57:28] <+weasel> man page isn't development docs. it's end-user docs [17:58:38] <+pili> hmmm, you're right [17:59:06] <+pili> now I'm wondering what we really want in docs.tpo, I know I have some notes on this but not on my travelling laptop [17:59:20] <+weasel> that's why I asked :) [17:59:30] <+weasel> docs sounds too ... wide? for "just" dev stuff [17:59:48] <+pili> ok, let me turn this around then... where would you put it? ;) [17:59:55] <+pili> or where do the developers want to have it? [18:00:15] <+pili> because if we're thinking about end-user docs for all products, then we already have tor browser at tb-manual.tpo [18:00:20] <+weasel> it depends on whether we want to add doxygen or javadoc things for other projects later, [18:00:21] <+pili> and that's not going to move to docs... [18:00:38] <+weasel> and it dependso on whether we want doxygen things for other tor branches. the latter nickm said they probably don't need. [18:01:02] <+weasel> I'd probably put it under src-ref.docs.torproject.org/tor/ [18:01:32] <+pili> nickm any strong opinions? or do you just want it somewhere? [18:02:33] <+nickm> not really. weasel's idea seems cool to me. [18:03:58] <+catalyst> how will this fit in with rendered versions of doc/HACKING if we start automatically generating those?

---

Let's continue this discussion here on this ticket

Wrt hostnames: Talked with Antonela et al on the vegas meeting today. The conclusion is that it's fine to use src-ref.docs.torproject.org/tor/ for now, so long as we are okay moving it later on if it turns out not to fit in some eventual docs hierarchy.

https://src-ref.docs.torproject.org/tor/ is now a thing.

Also see https://jenkins.torproject.org/job/tor-doxygen/ and https://jenkins.torproject.org/job/tor-doxygen-install/.

Please close if you think this is done.

Trac:
Status: new to needs_review

Replying to nickm:

Wrt hostnames: Talked with Antonela et al on the vegas meeting today. The conclusion is that it's fine to use src-ref.docs.torproject.org/tor/ for now, so long as we are okay moving it later on if it turns out not to fit in some eventual docs hierarchy. Sounds good to me :)

Replying to weasel:

Please close if you think this is done.

LGTM! Thanks, everybody!

Trac:
Status: needs_review to closed
Resolution: N/A to implemented

How about hosting doxygen of old versions, or at least maintained versions?

It helps to see doxygens of old versions to see how the codebase evolved.

Trac:
Username: willbarr
Resolution: implemented to N/A
Status: closed to reopened

Maybe open another ticket for that? It's not out of the question, but it's beyond the scope of what I'm able to work on in the next month timeframe.

Trac:
Status: reopened to closed
Resolution: N/A to implemented

Trac:
Cc: nickm, weasel, gaba to nickm, weasel, gaba, catalyst

closed

mentioned in issue #32292 (moved)

mentioned in issue #29214 (moved)

moved to tpo/core/tor#32101 (closed)

mentioned in issue tpo/web/trac#32292 (moved)

mentioned in issue tpo/web/dev#8