Skip to content
Permalink
Browse files
Add files to generate documentation with Sphinx
  • Loading branch information
@juga0
juga0 committed Apr 15, 2019
1 parent 7b386f2 commit 43c70ffdf6bee5f400cda1e526883e0c56ceaa6f
Showing with 231 additions and 2 deletions.
  1. +3 −2 .gitignore
  2. +19 −0 doc/Makefile
  3. +50 −0 doc/_static/tor-logo.svg
  4. +82 −0 doc/conf.py
  5. +37 −0 doc/index.rst
  6. +35 −0 doc/make.bat
  7. +5 −0 doc/requirements.txt
5 .gitignore
View file
@@ -95,9 +95,10 @@ uptime-*.json
/debian/tor.prerm.debhelper
/debian/tor.substvars

# /doc/
/doc/Makefile
# For the sphinx Makefile
# /doc/Makefile
/doc/Makefile.in
/doc/build
/doc/doxygen
/doc/tor.1
/doc/tor.1.in
19 doc/Makefile
View file
@@ -0,0 +1,19 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SOURCEDIR = .
BUILDDIR = build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
50 doc/_static/tor-logo.svg
View file
@@ -0,0 +1,50 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg width="82px" height="50px" viewBox="0 0 82 50" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<!-- Generator: Sketch 48.1 (47250) - http://www.bohemiancoding.com/sketch -->
<title>tor-logo</title>
<desc>Created with Sketch.</desc>
<defs></defs>
<g id="Support-Portal" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd" transform="translate(-164.000000, -49.000000)">
<g id="tor-logo" transform="translate(164.000000, 49.000000)" fill-rule="nonzero">
<g id="Group">
<g id="layer3_17_" transform="translate(27.606039, 0.000174)">
<g id="layer5_17_">
<g id="path2554_28_" transform="translate(14.569854, 0.000000)" fill="#68B044">
<path d="M3.9108555,3.69230769 L2.607237,8.92307692 C4.44763959,5.23076923 7.43829379,2.46153846 10.8123652,-7.10542736e-15 C8.35849509,2.92307692 6.05799185,5.76923077 4.67768991,8.69230769 C7.05487659,5.38461538 10.1988977,3.53846154 13.726336,2.38461538 C8.97196262,6.61538462 5.29115744,11.1538462 2.37718668,15.6923077 L0.0766834412,14.6923077 C0.536784088,11 1.91708603,7.30769231 3.9108555,3.69230769 Z" id="Shape"></path>
</g>
<g id="path2534_7_" transform="translate(0.000000, 13.076923)" fill="#F5F8DE">
<path d="M12.4227175,0.615384615 L16.7169902,2.38461538 C16.7169902,3.46153846 16.6403067,6.84615385 17.3304577,7.84615385 C24.5387012,17.1538462 23.3117661,35.6923077 15.8734723,36.1538462 C4.60100647,36.1538462 0.230050324,28.4615385 0.230050324,21.3846154 C0.230050324,14.9230769 7.97507788,10.6153846 12.5760844,6.84615385 C13.8030194,5.84615385 13.5729691,3.53846154 12.4227175,0.615384615 Z" id="Shape"></path>
</g>
<g id="path2536_18_" transform="translate(16.744548, 15.384615)" fill="#FFFFFF">
<path d="M0.0491253295,0 L1.58279415,0.769230769 C1.42942727,1.76923077 1.65947759,4.07692308 2.65636233,4.69230769 C7.18068536,7.53846154 11.4749581,10.6153846 13.1619938,13.6923077 C19.1433022,24.5384615 8.94440451,34.6153846 0.125808771,33.6153846 C4.88018212,30.0769231 6.33716751,22.7692308 4.49676492,14.7692308 C3.72993051,11.6153846 2.65636233,8.84615385 0.585909418,5.61538462 C-0.180924994,4.15384615 0.125808771,2.23076923 0.0491253295,0 Z" id="Shape"></path>
</g>
</g>
<g id="layer4_17_" transform="translate(3.834172, 15.384615)" fill="#010101">
<g id="path2540_18_" transform="translate(0.000000, 4.615385)">
<path d="M11.1957824,0.615384615 C10.8890486,2.30769231 10.5056314,5.38461538 9.04864606,6.46153846 C8.43517853,6.92307692 7.821711,7.30769231 7.13156003,7.76923077 C4.52432303,9.53846154 1.84040259,11.2307692 0.690150971,15.6153846 C0.460100647,16.5384615 0.690150971,17.5384615 0.843517853,18.4615385 C1.53366882,21.0769231 3.37407141,24 4.83105679,25.6153846 C4.83105679,25.6923077 5.13779056,25.8461538 5.13779056,25.9230769 C6.36472562,27.3846154 6.74814282,27.7692308 11.2724659,28.7692308 L11.1957824,29.3076923 C8.43517853,28.5384615 6.21135873,27.9230769 4.75437335,26.2307692 C4.75437335,26.2307692 4.52432303,25.9230769 4.52432303,25.9230769 C2.99065421,24.1538462 1.15025162,21.2307692 0.460100647,18.4615385 C0.230050324,17.3846154 -4.30211422e-14,16.5384615 0.306733765,15.3846154 C1.53366882,10.9230769 4.29427271,9.15384615 6.97819315,7.30769231 C7.59166068,6.92307692 8.35849509,6.53846154 8.89527918,6.07692308 C9.96884735,5.23076923 10.5823149,2.69230769 11.1957824,0.615384615 Z" id="Shape"></path>
</g>
<g id="path2542_18_" transform="translate(3.067338, 12.179487)">
<path d="M9.27869638,0.0512820513 C9.27869638,1.97435897 9.1253295,2.8974359 9.58543015,4.28205128 C9.89216391,5.05128205 10.8890486,6.20512821 11.1957824,7.28205128 C11.5791996,8.74358974 12.0393003,10.2820513 11.9626168,11.2820513 C11.9626168,12.3589744 11.8859334,14.4358974 11.4258327,16.6666667 C11.0424155,18.5128205 10.1988977,20.0512821 8.81859573,20.8974359 C7.36161035,20.5897436 5.67457465,20.1282051 4.67768991,19.2051282 C2.76060388,17.5128205 0.996884735,14.6666667 0.766834412,12.2051282 C0.613467529,10.2051282 2.45387012,7.20512821 5.06110712,5.74358974 C7.28492691,4.43589744 7.74502756,2.97435897 8.20512821,0.666666667 C7.51497723,2.74358974 6.90150971,4.43589744 4.83105679,5.51282051 C1.76371915,7.12820513 0.153366882,9.82051282 0.306733765,12.4358974 C0.536784088,15.7435897 1.84040259,17.974359 4.44763959,19.7435897 C5.52120776,20.5128205 7.59166068,21.3589744 8.89527918,21.5128205 L8.89527918,21.3589744 C9.89216391,21.2051282 11.119099,19.5897436 11.7325665,17.4358974 C12.2693506,15.5128205 12.4994009,12.974359 12.4227175,11.4358974 C12.4227175,10.5128205 11.9626168,8.51282051 11.2724659,6.74358974 C10.8890486,5.74358974 10.2755811,4.74358974 9.81548047,4.05128205 C9.50874671,3.35897436 9.50874671,1.82051282 9.27869638,0.0512820513 Z" id="Shape"></path>
</g>
<g id="path2544_18_" transform="translate(8.435179, 19.230769)">
<path d="M3.60412173,0.538461538 C3.60412173,1.84615385 4.14090582,3.46153846 4.37095615,5.15384615 C4.52432303,6.38461538 4.44763959,7.69230769 4.44763959,8.76923077 C4.44763959,10.0769231 3.98753894,12.3076923 3.37407141,13.4615385 C2.83728732,13.2307692 2.607237,12.9230769 2.22381979,12.4615385 C1.76371915,11.8461538 1.45698538,11.2307692 1.22693506,10.4615385 C0.996884735,9.92307692 0.766834412,9.30769231 0.613467529,8.53846154 C0.460100647,7.46153846 0.536784088,5.69230769 1.76371915,3.92307692 C2.68392044,2.53846154 2.91397076,2.38461538 3.29738797,0.846153846 C2.83728732,2.30769231 2.53055356,2.38461538 1.53366882,3.61538462 C0.383417206,4.92307692 0.230050324,6.84615385 0.230050324,8.46153846 C0.230050324,9.15384615 0.460100647,9.84615385 0.766834412,10.5384615 C1.07356818,11.3076923 1.3036185,12 1.68703571,12.5384615 C2.30050324,13.4615385 3.06733765,13.9230769 3.45075485,14 C3.45075485,14 3.45075485,14 3.45075485,14 C3.45075485,14 3.45075485,14 3.45075485,14 L3.45075485,13.9230769 C4.14090582,13.1538462 4.60100647,12.3076923 4.75437335,11.5384615 C4.90774023,10.6153846 4.98442368,9.61538462 5.06110712,8.46153846 C5.13779056,7.53846154 5.06110712,6.23076923 4.83105679,4.92307692 C4.44763959,3.38461538 3.83417206,1.69230769 3.60412173,0.538461538 Z" id="Shape"></path>
</g>
<g id="path2550_18_" transform="translate(11.502516, 3.076923)">
<path d="M0.766834412,0.538461538 C0.766834412,2.46153846 0.920201294,6 1.45698538,7.38461538 C1.61035226,7.84615385 2.99065421,9.92307692 3.9108555,12.4615385 C4.60100647,14.2307692 4.67768991,15.8461538 4.83105679,16.3076923 C5.29115744,18.3846154 4.75437335,21.9230769 3.98753894,25.2307692 C3.60412173,27 2.37718668,29.2307692 0.920201294,30.1538462 L0.613467529,30.6923077 C1.38030194,30.6923077 3.37407141,28.6923077 4.06422238,26.3076923 C5.214474,22.2307692 5.67457465,20.3076923 5.13779056,15.7692308 C5.06110712,15.3076923 4.90774023,13.8461538 4.21758926,12.2307692 C3.22070453,9.76923077 1.76371915,7.46153846 1.53366882,6.92307692 C1.3036185,6.15384615 0.843517853,2.84615385 0.766834412,0.538461538 Z" id="Shape"></path>
</g>
<g id="path2552_18_" transform="translate(11.502516, 0.000000)">
<path d="M1.45698538,0.230769231 C1.38030194,2.15384615 1.3036185,3.76923077 1.68703571,5.15384615 C2.07045291,6.76923077 4.14090582,9 4.98442368,11.6153846 C6.59477594,16.6153846 6.21135873,23.1538462 4.98442368,28.2307692 C4.52432303,30 2.45387012,32.6153846 0.383417206,33.4615385 L1.91708603,33.8461538 C2.76060388,33.8461538 4.90774023,31.7692308 5.75125809,29.4615385 C7.13156003,25.8461538 7.36161035,21.5384615 6.82482626,16.9230769 C6.82482626,16.4615385 6.05799185,12.5384615 5.36784088,10.9230769 C4.37095615,8.46153846 2.83728732,6.76923077 2.22381979,5.23076923 C1.76371915,4.07692308 1.61035226,1.07692308 1.91708603,0.384615385 L1.45698538,0.230769231 Z" id="Shape"></path>
</g>
</g>
</g>
<g id="path2528_14_" transform="translate(0.000000, 4.615385)" fill="#FFFFFF">
<path d="M2.07045291,0.153846154 L31.4402109,0.153846154 C32.5137791,0.153846154 33.5106638,1.07692308 33.5106638,2.23076923 L33.5106638,10.9230769 C33.5106638,12.0769231 32.5904625,13 31.4402109,13 L25.382219,13 C24.0019171,13 23.465133,13.7692308 23.465133,14.6153846 L23.465133,43.0769231 C23.465133,44 22.6982986,44.7692308 21.7780973,44.7692308 L11.8092499,44.7692308 C10.8890486,44.7692308 10.1988977,44 10.1988977,43.0769231 L10.1988977,14.3846154 C10.1988977,13.5384615 9.43206326,13 8.74191229,13 L2.07045291,13 C0.920201294,13 0,12.0769231 0,10.9230769 L0,2.23076923 C0,1.07692308 0.920201294,0.153846154 2.07045291,0.153846154 Z" id="Shape"></path>
</g>
<g id="path2532_14_" transform="translate(63.647256, 16.153846)" fill="#FFFFFF">
<path d="M16.333573,0.153846154 C17.2537743,0.153846154 18.0206087,0.923076923 18.0206087,1.84615385 L18.0206087,11.1538462 C18.0206087,12.3846154 18.0972921,12.8461538 16.6403067,12.8461538 C13.726336,12.8461538 12.4227175,14.3846154 12.4227175,16.0769231 L12.4227175,31.8461538 C12.4227175,32.6153846 11.7325665,33.2307692 10.8890486,33.2307692 L1.61035226,33.2307692 C0.766834412,33.2307692 0.0766834412,32.6153846 0.0766834412,31.8461538 L0.0766834412,13.9230769 C0.0766834412,13.6153846 0.0766834412,13.1538462 0.0766834412,12.9230769 C0.613467529,6.30769231 5.75125809,1 12.346034,0.307692308 C12.5760844,0.230769231 13.4196022,0.153846154 13.726336,0.153846154 L16.333573,0.153846154 Z" id="Shape"></path>
</g>
</g>
<path d="M55.2120776,25.2307692 C53.6017254,23.7692308 51.6846393,22.6153846 49.6141864,21.4615385 C48.6939851,20.9230769 45.8566978,18.7692308 46.8535826,15.6153846 L39.7220225,12.6923077 L39.2619219,13.0769231 C41.6391086,17.3846154 40.4121735,19.6153846 39.2619219,20.4615385 C36.8847352,22.0769231 33.4339803,24.1538462 31.6702612,26 C28.3728732,29.3846154 27.3759885,32.6923077 27.6827223,37 C27.989456,42.5384615 31.976995,47.0769231 37.3448358,48.9230769 C39.7220225,49.6923077 41.8691589,49.7692308 44.2463456,49.7692308 C48.1572011,49.7692308 52.14474,48.7692308 54.9820273,46.3076923 C58.049365,43.7692308 59.8897676,39.9230769 59.8897676,35.9230769 C59.8897676,31.6923077 58.2027318,27.9230769 55.2120776,25.2307692 Z M54.1385095,45.3076923 C51.5312725,47.5384615 46.7002157,49 44.1696621,48.9230769 C41.3323748,48.7692308 38.5717709,48.3076923 36.1945842,47.1538462 C31.9003115,45.0769231 29.0630242,40.6153846 28.9096573,36.9230769 C28.5262401,29.4615385 32.0536784,27.3076923 35.3510664,24.6153846 C37.191469,23.0769231 39.798706,22.3076923 41.2556913,19.6153846 C41.5624251,19 41.715792,17.6923077 41.3323748,16.3846154 C41.1790079,15.9230769 40.4888569,14.2307692 40.2588066,13.9230769 L45.6266475,16.3076923 C44.9364965,18.7692308 47.0069494,21.3076923 48.6173017,22.2307692 C50.227654,23.1538462 52.834891,24.8461538 54.3685598,26.3076923 C57.1291637,28.7692308 58.5861491,32.2307692 58.5861491,35.9230769 C58.5094656,39.3846154 56.9757968,42.9230769 54.1385095,45.3076923 Z" id="Shape" fill="#010101"></path>
</g>
</g>
</svg>
82 doc/conf.py
View file
@@ -0,0 +1,82 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# http://www.sphinx-doc.org/en/master/config

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
import sphinx_bootstrap_theme

# -- Project information -----------------------------------------------------

# This variables should be parsed and not hard coded.
# As well as version.
project = 'Tor codebase documentation'
copyright = '2019, The Tor Project'
author = 'The Tor Project'
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = ''


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]

# Add any paths that contain templates here, relative to this directory.
# templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []

source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser',
}

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
source_suffix = ['.rst', '.md']

# The master toctree document.
master_doc = 'index'

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# Use bootstrap because torproject.org uses bootstrap.
html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
html_logo = "_static/tor-logo.svg"
# From https://bootswatch.com/3/
html_theme_options = {
'bootswatch_theme': "flatly",
}
# bootstrap could be replaced by a custom theme for all the documentation
# created with Sphinx, see # http://www.sphinx-doc.org/en/master/theming.html.
# Sphinx uses Jinja engine, same as lektor, so it seems not difficult not to
# base it on https://gitweb.torproject.org/project/web/template.git.
# If the directory templates and static are just copied in this project
# static and templates files respectively, make html fails:
# Reason: TemplateAssertionError("no filter named 'asseturl'",)
37 doc/index.rst
View file
@@ -0,0 +1,37 @@
.. Tor codebase documentation documentation master file, created by
sphinx-quickstart on Sun Apr 7 06:30:04 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Tor codebase's documentation!
========================================

.. Ordered according they are mentioned in README.1st
.. Other files might need to be ordered in a different way.
.. toctree::
:maxdepth: 2
:caption: Contents:

HACKING/README.1st
HACKING/GettingStarted
HACKING/CodingStandards
HACKING/WritingTests
HACKING/HelpfulTools
HACKING/Maintaining
HACKING/HowToReview
HACKING/ReleasingTor
HACKING/CodeStructure
HACKING/Module
HACKING/Tracing
HACKING/Fuzzing
HACKING/GettingStartedRust
HACKING/CodingStandardsRust
HACKING/android/Simpleperf

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
35 doc/make.bat
View file
@@ -0,0 +1,35 @@
@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

if "%1" == "" goto help

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%

:end
popd
5 doc/requirements.txt
View file
@@ -0,0 +1,5 @@
# Minimal requirements, other libraries are installed when these get installed.
# Minor versions might work, but pip has the concept of XX
recommonmark==0.5.0
Sphinx==1.8.0
sphinx-bootstrap-theme==0.7.1

0 comments on commit 43c70ff

Please sign in to comment.