Opened 3 months ago

Last modified 5 days ago

#29200 assigned defect

Make more accessible Core Tor documentation

Reported by: juga Owned by: pili
Priority: Medium Milestone: website redesign
Component: Webpages/Website Version:
Severity: Normal Keywords: documentation, ux-team
Cc: antonela, gaba, ahf, pili Actual Points:
Parent ID: #24132 Points:
Reviewer: Sponsor:

Description

There's Core Tor documentation distributed in three (at least) sources. Even if it's documentation intended for developers, it'd be great that it would be more accessible by providing the HTML version online and using some torproject.org subdomain or path or links.
The sources are:

I can provide scripts to generate/convert the documentation automatically.
We would need to decide where to put it, maybe get subdomain and get access to the server where it would live.

Child Tickets

Change History (10)

comment:1 Changed 3 months ago by gaba

Cc: gaba added
Keywords: documentation added

comment:2 Changed 3 months ago by gaba

Cc: ahf added

There was some discussion of maybe converting what we have to send it to https://readthedocs.org/

comment:3 Changed 2 months ago by juga

Sphinx (http://www.sphinx-doc.org/en/stable/) is the tool to generate html from markdown or restructured text and python docstrings.
https://readthedocs.org/ is a service that automatically publish the html from the source documentation.
As ahf pointed out, https://breathe.readthedocs.io/en/latest/ can be used to format doxygen documentation as sphinx html.

comment:4 Changed 4 weeks ago by antonela

https://www.gitbook.com/ is another option for our docs and is free for non-profits

comment:5 Changed 4 weeks ago by antonela

Cc: pili added
Component: UX- Select a component
Keywords: ux-team added

comment:6 Changed 4 weeks ago by gk

Component: - Select a componentCore Tor

It seems this does not belong under the UX component, but having the component in limbo is not good either. Moving tentatively, to core tor. Please, move this to a different component if it fits there better.

comment:7 Changed 5 days ago by juga

Component: Core TorWebpages/Website
Milestone: website redesign
Parent ID: #24132

It probably belongs to Webpages/Website, parent #24132 and milestone website redesign.

comment:8 Changed 5 days ago by juga

I configured torguts and tor to use Sphinx for the markdown documentation.
The branches:

To see how it looks like:

Note the comments on creating a Sphinx theme for Tor. I think it would be easy basing it on the Sphinx bootstrap theme.

I tried to build the doxygen documentation also with Sphinx using breathe, and i managed to get all in one package (left the branch in https://github.com/juga0/tor/commits/wip_sphinx_doc_doxygen), but it'd require still more work and i'm not sure it's worth. Doxygen itself could be configured to use templates and custom css, maybe that require less work.

I can remove those readthedocs domains once it's decided what to do.
The documentation could live in readthedocs and have a torproject subdomain that point to it, or it could be deployed in torproject infraestructure having a simple script that pull the repositories every X time and run make html in the documentation directory.

comment:9 Changed 5 days ago by antonela

Owner: changed from antonela to pili
Status: newassigned

comment:10 Changed 5 days ago by gaba

Nice! Thanks!

Note: See TracTickets for help on using tickets.