Opened 2 months ago

Closed 7 weeks ago

Last modified 6 weeks ago

#32101 closed task (implemented)

Generate and publish doxygen output automatically

Reported by: nickm Owned by:
Priority: Medium Milestone: Tor: 0.4.3.x-final
Component: Core Tor/Tor Version:
Severity: Normal Keywords: network-team-roadmap-november, s31-docs
Cc: nickm, weasel, gaba, catalyst Actual Points:
Parent ID: #29214 Points:
Reviewer: Sponsor: Sponsor31-can

Description

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.

Child Tickets

Change History (12)

comment:1 Changed 2 months ago by weasel

Cc: weasel added

comment:2 Changed 2 months ago by weasel

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

comment:3 Changed 2 months ago by weasel

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.

comment:4 Changed 8 weeks ago by gaba

Cc: gaba added

comment:5 Changed 8 weeks ago by pili

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

Last edited 8 weeks ago by pili (previous) (diff)

comment:6 Changed 8 weeks ago by 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.

comment:7 Changed 7 weeks ago by weasel

Status: newneeds_review

comment:8 in reply to:  6 Changed 7 weeks ago by pili

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 :)

comment:9 in reply to:  7 Changed 7 weeks ago by nickm

Resolution: implemented
Status: needs_reviewclosed

Replying to weasel:

Please close if you think this is done.

LGTM! Thanks, everybody!

comment:10 Changed 7 weeks ago by willbarr

Resolution: implemented
Status: closedreopened

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.

comment:11 Changed 7 weeks ago by nickm

Resolution: implemented
Status: reopenedclosed

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.

comment:12 Changed 6 weeks ago by catalyst

Cc: catalyst added
Note: See TracTickets for help on using tickets.