Skip to content

Commit e5f09f8

Browse files
JasonGrace2282JasonGrace2282
authored
Start adding (better) docs to Tin (#42)
This PR aims to get all the Sphinx stuff done Adding docstrings and such will be done in a future PR This PR also adds `pydocstyle` to ruff, to enforce google docstring conventions.
1 parent 06a0ed7 commit e5f09f8

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+1402
-141
lines changed

‎.github/workflows/ci.yml

+32
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,35 @@ jobs:
3939

4040
- name: Run Tests
4141
run: pipenv run python3 manage.py test
42+
docs:
43+
runs-on: ubuntu-latest
44+
45+
strategy:
46+
matrix:
47+
python-version:
48+
- 3.8
49+
50+
steps:
51+
- name: Set up repo
52+
uses: actions/checkout@v2
53+
54+
- name: Set up Python ${{ matrix.python-version }}
55+
uses: actions/setup-python@v5
56+
with:
57+
python-version: ${{ matrix.python-version }}
58+
cache: pipenv
59+
60+
- name: Install Sphinx
61+
run: sudo apt-get install python3-sphinx
62+
63+
- name: Install pipenv
64+
run: pip install pipenv
65+
66+
- name: Install dependencies
67+
run: pipenv install --dev
68+
69+
- name: Build Docs
70+
run: |
71+
72+
cd docs
73+
pipenv run make html

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,5 @@ tin/settings/secret.py
99
tin/serve
1010

1111
.idea/
12+
docs/build/
13+
docs/source/reference/

‎.pre-commit-config.yaml

-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,6 @@ repos:
2929
files: ^tin/.*
3030
name: ruff lint
3131
- id: ruff-format
32-
files: ^tin/.*
3332
- repo: https://github.com/pre-commit/mirrors-prettier
3433
rev: v4.0.0-alpha.8
3534
hooks:

‎Pipfile

+5
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,11 @@ pytest-django = "~=4.8"
2828
django-stubs = "*"
2929
pre-commit = "*"
3030
typing-extensions = "*"
31+
sphinx = "*"
32+
furo = "*"
33+
myst-parser = "*"
34+
sphinx-copybutton = "*"
35+
sphinxcontrib-django = "*"
3136

3237
[requires]
3338
python_version = "3.8"

‎Pipfile.lock

+493-71
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<p align="center">
2-
<img src="./assets/tin-logo.gif" width="500">
2+
<img src="docs/source/_static/tin-logo.gif" width="500">
33
</p>
44
<br>
55
<p align="center">

‎assets/logo.py

+4-3
Original file line numberDiff line numberDiff line change
@@ -20,16 +20,16 @@ def construct(self):
2020

2121
subtext = Text("TJHSST's Code Autograder", color=BEIGE).next_to(full, DOWN, buff=2)
2222

23-
name.to_edge(RIGHT).shift(RIGHT*name.width)
24-
full.to_edge(LEFT).shift(LEFT*full.width)
23+
name.to_edge(RIGHT).shift(RIGHT * name.width)
24+
full.to_edge(LEFT).shift(LEFT * full.width)
2525
self.play(
2626
name.animate(rate_func=rate_functions.ease_out_bounce).set_x(0).set_color(GREEN),
2727
full.animate(rate_func=rate_functions.ease_out_bounce).set_x(0).set_color(BEIGE),
2828
)
2929
self.play(Create(subtext))
3030
self.wait(4)
3131
self.play(Uncreate(VGroup(name, full, subtext)), run_time=1)
32-
self.wait(.1)
32+
self.wait(0.1)
3333

3434

3535
def main():
@@ -41,5 +41,6 @@ def main():
4141
with tempconfig(args):
4242
Logo().render()
4343

44+
4445
if __name__ == "__main__":
4546
main()

‎conftest.py

+3-1
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,11 @@
66
"tin.tests.fixtures",
77
]
88

9+
910
@pytest.fixture(autouse=True)
1011
def set_default_language():
11-
activate('en')
12+
activate("en")
13+
1214

1315
@pytest.fixture(autouse=True)
1416
def use_db_on_all_test(db):

‎create_debug_users.py

-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@
1616
exit()
1717

1818

19-
2019
from tin.tests.create_users import add_users_to_database
2120

2221
password = input("Enter password for all users: ")

‎docs/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎assets/tin-logo.gif ‎docs/source/_static/tin-logo.gif

File renamed without changes.

‎docs/source/_static/tjcsl-logo.png

34 KB
Loading

‎docs/source/_templates/autosummary/class.rst

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{{ name | escape | underline}}
2+
3+
Qualified name: ``{{ fullname | escape }}``
4+
5+
.. currentmodule:: {{ module }}
6+
7+
.. autoclass:: {{ objname }}
8+
:show-inheritance:
9+
:members:
10+
:private-members:
11+
12+
13+
{% block methods %}
14+
{%- if methods %}
15+
.. rubric:: {{ _('Methods') }}
16+
17+
.. autosummary::
18+
:nosignatures:
19+
{% for item in methods if item != '__init__' and item[0] != '_' and item not in inherited_members %}
20+
~{{ name }}.{{ item }}
21+
{%- endfor %}
22+
{%- endif %}
23+
{%- endblock %}
24+
25+
{% block attributes %}
26+
{%- if attributes %}
27+
.. rubric:: {{ _('Attributes') }}
28+
29+
.. autosummary::
30+
{% for item in attributes if item[0] != '_' and item not in inherited_members %}
31+
~{{ name }}.{{ item }}
32+
{%- endfor %}
33+
{%- endif %}
34+
{% endblock %}

‎docs/source/_templates/autosummary/module.rst

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
{{ name | escape | underline }}
2+
3+
.. currentmodule:: {{ fullname }}
4+
5+
.. automodule:: {{ fullname }}
6+
7+
{% block classes %}
8+
{% if classes %}
9+
.. rubric:: Classes
10+
11+
.. autosummary::
12+
:toctree: .
13+
:nosignatures:
14+
{% for class in classes %}
15+
{{ class }}
16+
{% endfor %}
17+
{% endif %}
18+
{% endblock %}
19+
20+
{% block functions %}
21+
{% if functions %}
22+
.. rubric:: {{ _('Functions') }}
23+
24+
{% for item in functions %}
25+
.. autofunction:: {{ item }}
26+
{%- endfor %}
27+
{% endif %}
28+
{% endblock %}
29+
30+
{% block exceptions %}
31+
{% if exceptions %}
32+
.. rubric:: {{ _('Exceptions') }}
33+
34+
.. autosummary::
35+
{% for item in exceptions %}
36+
{{ item }}
37+
{%- endfor %}
38+
{% endif %}
39+
{% endblock %}
40+
41+
{% block modules %}
42+
{% if modules %}
43+
.. rubric:: Modules
44+
45+
.. autosummary::
46+
:toctree:
47+
:recursive:
48+
{% for item in modules %}
49+
{{ item }}
50+
{%- endfor %}
51+
{% endif %}
52+
{% endblock %}

‎docs/source/conf.py

+129
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
from __future__ import annotations
9+
10+
import os
11+
import sys
12+
from datetime import datetime
13+
14+
15+
# -- Path setup --------------------------------------------------------------
16+
# If extensions (or modules to document with autodoc) are in another directory,
17+
# add these directories to sys.path here. If the directory is relative to the
18+
# documentation root, use os.path.abspath to make it absolute, like shown here.
19+
20+
21+
sys.path.insert(0, os.path.abspath("../../"))
22+
23+
# -- Project information -----------------------------------------------------
24+
25+
project = "Tin"
26+
copyright = f"2020-{datetime.now().year}, Sysadmins at TJ CSL"
27+
author = "Sysadmins at TJ CSL"
28+
29+
django_settings = "tin.settings"
30+
31+
# -- General configuration ---------------------------------------------------
32+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
33+
34+
extensions = [
35+
"sphinx.ext.autodoc",
36+
"sphinx.ext.autosummary",
37+
"sphinx.ext.intersphinx",
38+
"sphinx.ext.extlinks",
39+
"sphinx.ext.napoleon",
40+
"sphinx.ext.viewcode",
41+
"sphinx_copybutton",
42+
"myst_parser",
43+
"sphinxcontrib_django",
44+
]
45+
46+
add_function_parentheses = False
47+
48+
# Automatically generate stub pages when using the .. autosummary directive
49+
autosummary_generate = True
50+
51+
# controls whether functions documented by the autofunction directive
52+
# appear with their full module names
53+
add_module_names = False
54+
55+
# napoleon settings
56+
napoleon_numpy_docstring = False # force google
57+
napoleon_include_special_with_doc = False
58+
59+
napoleon_custom_sections = [
60+
("Special", "params_style"),
61+
]
62+
63+
templates_path = ["_templates"]
64+
exclude_patterns = []
65+
66+
# We depend on sphinxcontrib_django for intersphinx mappings
67+
68+
extlinks = {
69+
"issue": ("https://github.com/tjcsl/tin/issues/%s", "issue %s"),
70+
"pr": ("https://github.com/tjcsl/tin/pull/%s", "pr #%s"),
71+
}
72+
# warn hardcoded links
73+
extlinks_detect_hardcoded_links = True
74+
75+
# -- Options for HTML output -------------------------------------------------
76+
77+
# The theme to use for HTML and HTML Help pages. See the documentation for
78+
# a list of builtin themes.
79+
#
80+
81+
html_theme = "furo"
82+
83+
# use |br| for linebreak
84+
rst_prolog = """
85+
.. |br| raw:: html
86+
87+
<br/>
88+
"""
89+
90+
# Add any paths that contain custom static files (such as style sheets) here,
91+
# relative to this directory. They are copied after the builtin static files,
92+
# so a file named "default.css" will overwrite the builtin "default.css".
93+
html_static_path = ["_static"]
94+
95+
html_theme_options = {
96+
"source_repository": "https://github.com/tjcsl/tin/",
97+
"source_branch": "main",
98+
"source_directory": "docs/source/",
99+
"light_logo": "tjcsl-logo.png",
100+
"dark_logo": "tjcsl-logo.png",
101+
"light_css_variables": {
102+
"color-content-foreground": "#000000",
103+
"color-background-primary": "#ffffff",
104+
"color-background-border": "#ffffff",
105+
"color-sidebar-background": "#f8f9fb",
106+
"color-brand-content": "#1c00e3",
107+
"color-brand-primary": "#192bd0",
108+
"color-link": "#c93434",
109+
"color-link--hover": "#5b0000",
110+
"color-inline-code-background": "#f6f6f6;",
111+
"color-foreground-secondary": "#000",
112+
},
113+
"dark_css_variables": {
114+
"color-content-foreground": "#ffffffd9",
115+
"color-background-primary": "#131416",
116+
"color-background-border": "#303335",
117+
"color-sidebar-background": "#1a1c1e",
118+
"color-brand-content": "#2196f3",
119+
"color-brand-primary": "#007fff",
120+
"color-link": "#51ba86",
121+
"color-link--hover": "#9cefc6",
122+
"color-inline-code-background": "#262626",
123+
"color-foreground-secondary": "#ffffffd9",
124+
},
125+
}
126+
html_title = "Tin: Turn-In"
127+
128+
# This specifies any additional css files that will override the theme's
129+
html_css_files = []

0 commit comments

Comments
 (0)