[tor-bugs] #32101 [Core Tor/Tor]: Generate and publish doxygen output automatically

[Tor Bug Tracker & Wiki]

#32101: Generate and publish doxygen output automatically
-------------------------------------------------+-------------------------
 Reporter:  nickm                                |          Owner:  (none)
     Type:  task                                 |         Status:  new
 Priority:  Medium                               |      Milestone:  Tor:
                                                 |  0.4.3.x-final
Component:  Core Tor/Tor                         |        Version:
 Severity:  Normal                               |     Resolution:
 Keywords:  network-team-roadmap-november,       |  Actual Points:
  s31-docs                                       |
Parent ID:  #29214                               |         Points:
 Reviewer:                                       |        Sponsor:
                                                 |  Sponsor31-can
-------------------------------------------------+-------------------------

Comment (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:55:22]      dunqan
 (~dunqan at pool-72-92-237-215.prvdri.fios.verizon.net) left IRC (Quit: My
 MacBook Air has gone to sleep. ZZZzzz…)
 [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

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/32101#comment:5>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online