From 1bcc1a7d93c8527e3e0961ea7fab4c7b1c581630 Mon Sep 17 00:00:00 2001 From: JasonGrace2282 Date: Sun, 25 Aug 2024 14:26:13 -0400 Subject: [PATCH] feat: modernize documentation setup --- .github/workflows/ci.yml | 6 +- .gitignore | 1 + README.rst | 4 +- ci/spec.yml | 12 +- docs/Makefile | 24 +++ docs/_ext/djangodocs.py | 8 - docs/_templates/relations.html | 0 docs/developing/styleguide.rst | 107 ---------- docs/requirements.txt | 4 + docs/rtd-requirements.txt | 68 ------ docs/{ => source}/_static/custom.css | 0 docs/{ => source/_static}/favicon.ico | Bin docs/source/_static/logo-dark.svg | 1 + docs/source/_static/logo-light.svg | 1 + docs/source/_templates/autosummary/class.rst | 34 +++ docs/source/_templates/autosummary/module.rst | 52 +++++ docs/{ => source}/architecture/index.rst | 0 docs/{ => source}/conf.py | 194 ++++++------------ .../source/developing/contributing.md | 6 +- .../{ => source}/developing/eighth-models.rst | 0 docs/{ => source}/developing/howto.rst | 35 +++- docs/{ => source}/developing/index.rst | 1 + docs/{ => source}/developing/oauth.rst | 0 docs/{ => source}/developing/requirements.rst | 0 docs/source/developing/styleguide.rst | 96 +++++++++ docs/{ => source}/developing/testing.rst | 10 +- docs/{ => source}/developing/updates.rst | 15 +- .../source/developing/usernames.md | 0 docs/{ => source}/index.rst | 2 +- docs/source/reference_index.rst | 48 +++++ docs/source/reference_index/announcements.rst | 15 ++ docs/source/reference_index/api.rst | 12 ++ docs/source/reference_index/auth.rst | 17 ++ docs/source/reference_index/bus.rst | 16 ++ docs/source/reference_index/cslapps.rst | 13 ++ docs/source/reference_index/customthemes.rst | 11 + docs/source/reference_index/dashboard.rst | 11 + docs/source/reference_index/dataimport.rst | 9 + docs/source/reference_index/django.rst | 9 + docs/source/reference_index/eighth.rst | 38 ++++ docs/source/reference_index/eighth_views.rst | 17 ++ docs/source/reference_index/emailfwd.rst | 12 ++ docs/source/reference_index/emerg.rst | 11 + docs/source/reference_index/enrichment.rst | 13 ++ docs/source/reference_index/error.rst | 11 + docs/source/reference_index/events.rst | 13 ++ docs/source/reference_index/features.rst | 12 ++ docs/source/reference_index/feedback.rst | 13 ++ docs/source/reference_index/files.rst | 13 ++ docs/source/reference_index/groups.rst | 13 ++ docs/source/reference_index/itemreg.rst | 13 ++ docs/source/reference_index/logs.rst | 13 ++ docs/source/reference_index/lostfound.rst | 13 ++ docs/source/reference_index/middleware.rst | 20 ++ docs/source/reference_index/nomination.rst | 12 ++ docs/source/reference_index/notifications.rst | 13 ++ docs/source/reference_index/oauth.rst | 12 ++ docs/source/reference_index/parking.rst | 13 ++ docs/source/reference_index/polls.rst | 13 ++ docs/source/reference_index/preferences.rst | 13 ++ docs/source/reference_index/printing.rst | 13 ++ docs/source/reference_index/schedule.rst | 13 ++ docs/source/reference_index/search.rst | 11 + docs/source/reference_index/seniors.rst | 13 ++ docs/source/reference_index/sessionmgmt.rst | 13 ++ docs/source/reference_index/signage.rst | 15 ++ docs/source/reference_index/templatetags.rst | 20 ++ docs/source/reference_index/testing.rst | 11 + docs/source/reference_index/users.rst | 15 ++ docs/source/reference_index/utils.rst | 19 ++ docs/source/reference_index/welcome.rst | 11 + SECURITY.md => docs/source/security.md | 1 + docs/{ => source}/setup/index.rst | 1 + docs/{ => source}/setup/server.rst | 0 SETUP.md => docs/source/setup/setup.md | 0 intranet/apps/cslapps/models.py | 17 +- intranet/apps/dashboard/views.py | 8 +- scripts/build_docs.sh | 6 - scripts/build_sources.sh | 5 - scripts/check.sh | 21 -- scripts/format.sh | 4 - scripts/lint.sh | 4 - scripts/push_docs.sh | 2 +- scripts/static_templates_format.sh | 7 - 84 files changed, 966 insertions(+), 407 deletions(-) create mode 100644 docs/Makefile delete mode 100644 docs/_ext/djangodocs.py delete mode 100644 docs/_templates/relations.html delete mode 100644 docs/developing/styleguide.rst create mode 100644 docs/requirements.txt delete mode 100644 docs/rtd-requirements.txt rename docs/{ => source}/_static/custom.css (100%) rename docs/{ => source/_static}/favicon.ico (100%) create mode 100644 docs/source/_static/logo-dark.svg create mode 100644 docs/source/_static/logo-light.svg create mode 100644 docs/source/_templates/autosummary/class.rst create mode 100644 docs/source/_templates/autosummary/module.rst rename docs/{ => source}/architecture/index.rst (100%) rename docs/{ => source}/conf.py (58%) rename CONTRIBUTING.md => docs/source/developing/contributing.md (78%) rename docs/{ => source}/developing/eighth-models.rst (100%) rename docs/{ => source}/developing/howto.rst (75%) rename docs/{ => source}/developing/index.rst (85%) rename docs/{ => source}/developing/oauth.rst (100%) rename docs/{ => source}/developing/requirements.rst (100%) create mode 100644 docs/source/developing/styleguide.rst rename docs/{ => source}/developing/testing.rst (81%) rename docs/{ => source}/developing/updates.rst (63%) rename USERNAMES.md => docs/source/developing/usernames.md (100%) rename docs/{ => source}/index.rst (98%) create mode 100644 docs/source/reference_index.rst create mode 100644 docs/source/reference_index/announcements.rst create mode 100644 docs/source/reference_index/api.rst create mode 100644 docs/source/reference_index/auth.rst create mode 100644 docs/source/reference_index/bus.rst create mode 100644 docs/source/reference_index/cslapps.rst create mode 100644 docs/source/reference_index/customthemes.rst create mode 100644 docs/source/reference_index/dashboard.rst create mode 100644 docs/source/reference_index/dataimport.rst create mode 100644 docs/source/reference_index/django.rst create mode 100644 docs/source/reference_index/eighth.rst create mode 100644 docs/source/reference_index/eighth_views.rst create mode 100644 docs/source/reference_index/emailfwd.rst create mode 100644 docs/source/reference_index/emerg.rst create mode 100644 docs/source/reference_index/enrichment.rst create mode 100644 docs/source/reference_index/error.rst create mode 100644 docs/source/reference_index/events.rst create mode 100644 docs/source/reference_index/features.rst create mode 100644 docs/source/reference_index/feedback.rst create mode 100644 docs/source/reference_index/files.rst create mode 100644 docs/source/reference_index/groups.rst create mode 100644 docs/source/reference_index/itemreg.rst create mode 100644 docs/source/reference_index/logs.rst create mode 100644 docs/source/reference_index/lostfound.rst create mode 100644 docs/source/reference_index/middleware.rst create mode 100644 docs/source/reference_index/nomination.rst create mode 100644 docs/source/reference_index/notifications.rst create mode 100644 docs/source/reference_index/oauth.rst create mode 100644 docs/source/reference_index/parking.rst create mode 100644 docs/source/reference_index/polls.rst create mode 100644 docs/source/reference_index/preferences.rst create mode 100644 docs/source/reference_index/printing.rst create mode 100644 docs/source/reference_index/schedule.rst create mode 100644 docs/source/reference_index/search.rst create mode 100644 docs/source/reference_index/seniors.rst create mode 100644 docs/source/reference_index/sessionmgmt.rst create mode 100644 docs/source/reference_index/signage.rst create mode 100644 docs/source/reference_index/templatetags.rst create mode 100644 docs/source/reference_index/testing.rst create mode 100644 docs/source/reference_index/users.rst create mode 100644 docs/source/reference_index/utils.rst create mode 100644 docs/source/reference_index/welcome.rst rename SECURITY.md => docs/source/security.md (97%) rename docs/{ => source}/setup/index.rst (74%) rename docs/{ => source}/setup/server.rst (100%) rename SETUP.md => docs/source/setup/setup.md (100%) delete mode 100755 scripts/build_docs.sh delete mode 100755 scripts/build_sources.sh delete mode 100755 scripts/check.sh delete mode 100755 scripts/format.sh delete mode 100755 scripts/lint.sh delete mode 100755 scripts/static_templates_format.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4932e11996e..6f0be986fd9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -118,9 +118,13 @@ "if": "github.event_name == 'push' && (github.repository_owner != 'tjcsl' || github.ref != 'refs/heads/master' || github.ref != 'refs/heads/dev')", "run": "git fetch origin ${{ github.event.before }} && ./scripts/validate-commit-messages.py ${{ github.event.before }}..${{ github.event.after }}" }, + { + "name": "Install docs dependencies", + "run": "# sphinxcontrib_django imports our django project, so we need the deps\npip install -U -r requirements.txt\ncd docs\npip install -U -r requirements.txt\n" + }, { "name": "Build docs", - "run": "./scripts/build_ensure_no_changes.sh ./scripts/build_docs.sh" + "run": "cd docs\nmake html\n" }, { "name": "Push docs", diff --git a/.gitignore b/.gitignore index 18e47145c08..2192df5edab 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ Pipfile build .coverage dist/*.tar.gz +docs/source/reference # General ignores *.crt diff --git a/README.rst b/README.rst index f868b6130e1..e7cc24ccc58 100644 --- a/README.rst +++ b/README.rst @@ -20,10 +20,10 @@ Documentation (in RestructuredText format) is available inside the "docs" folder **Ion now requires Python 3.8+** Python 3.8.5 is currently used in both production and testing environments. -**How can I create a testing environment?** Read the section on `Setting up a Dev Environment `_ in the documentation. +**How can I create a testing environment?** Read the section on `Setting up a Dev Environment `_ in the documentation. **How can I contribute to Ion? How can I report a bug? How can I report a security issue/vulnerability?** -Please read our `contributing guide `_ for more information. +Please read our `contributing guide `_ for more information. Current Intranet maintainers: `alanzhu0 `_ and `NotFish232 `_ diff --git a/ci/spec.yml b/ci/spec.yml index ee902f34ea7..b394a842f54 100644 --- a/ci/spec.yml +++ b/ci/spec.yml @@ -119,8 +119,18 @@ jobs: run: 'git fetch origin ${{ github.event.before }} && ./scripts/validate-commit-messages.py ${{ github.event.before }}..${{ github.event.after }}' # Build/push docs + - name: Install docs dependencies + run: | + # sphinxcontrib_django imports our django project, so we need the deps + pip install -U -r requirements.txt + cd docs + pip install -U -r requirements.txt + - name: Build docs - run: ./scripts/build_ensure_no_changes.sh ./scripts/build_docs.sh + run: | + cd docs + make html + - name: Push docs # Only run for pushes to the main Ion repo if: github.event_name == 'push' && github.ref == 'refs/heads/master' && github.repository_owner == 'tjcsl' && matrix.python-version == 3.8 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000000..7b289759879 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,24 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +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 + +cleanall: clean + @echo "Cleaning all references" + @rm source/reference/* + +# 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) diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py deleted file mode 100644 index 07897109504..00000000000 --- a/docs/_ext/djangodocs.py +++ /dev/null @@ -1,8 +0,0 @@ -# -*- coding: utf-8 -*- -def setup(app): - """Setup for djangodocs.""" - app.add_crossref_type( - directivename="setting", - rolename="setting", - indextemplate="pair: %s; setting", - ) diff --git a/docs/_templates/relations.html b/docs/_templates/relations.html deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/docs/developing/styleguide.rst b/docs/developing/styleguide.rst deleted file mode 100644 index 15abe4fc1f2..00000000000 --- a/docs/developing/styleguide.rst +++ /dev/null @@ -1,107 +0,0 @@ -****************** -Coding Style Guide -****************** - -Follow `PEP8 `_ (the official style guide for Python). Most PEP8 formatting conventions are enforced in the build by ``pylint``, ``flake8``, and a combination of ``black``, ``autopep8``, and ``isort``. Therefore, if you do not follow them, the build may not pass. - -However, for Ion, we limit the lengths of lines to 150 characters, not 80 characters. - -Note: CSS/JS/template formatting is enforced by ``scripts/static_templates_format.sh``. Currently, this just strips trailing whitespace. - -Main points -=========== - -- Indent using 4 spaces. -- Use underscores in favor of camel case for all names except the names of classes. -- Limit the line length of docstrings or comments to 72 characters. -- Separate top-level functions and class definitions with two blank lines. -- Separate method definitions inside a class with a single blank line. -- Use two spaces before inline comments and one space between the pound sign and comment. -- Use a plugin for your text editor to check for/remind you of PEP8 conventions. -- When in doubt, running ``./scripts/format.sh`` will fix a lot of things. -- Capitalize and punctuate comments and Git commit messages properly. - -What is enforced in the build -============================= - -At the time of this writing, the GitHub Actions build runs the following commands: - -.. code-block:: sh - - flake8 --max-line-length 150 --exclude=*/migrations/* . - pylint --jobs=0 --disable=fixme,broad-except,global-statement,attribute-defined-outside-init intranet/ - isort --check --recursive intranet - ./scripts.format.sh - ./scripts/static_templates_format.sh # Static/template files - -Note: When the ``./scripts/format.sh`` and ``./scripts/static_templates_format.sh`` checks are run, the build will fail if they have to make any changes. - -``flake8`` is a PEP8 style checker, ``pylint`` is a linter (but it also enforces some PEP8 conventions), and ``isort``, when called with these options, checks that all imports are sorted alphabetically. - -``./scripts/format.sh`` runs ``black intranet && autopep8 --in-place --recursive intranet && isort --recursive intranet``. The reason for the multiple commands is that ``black`` introduces certain formatting changes which ``flake8``/``pylint`` do not agree with (and offers no options to change them), so we have ``autopep8`` fix it. - -It is recommended that you run all of these locally before opening a pull request (though the Ion developers sometimes skip running the ``pylint`` check locally because it takes a long time to run). All of them are intended to be run from the root directory of the Git repository. - -If ``flake8`` or ``pylint`` throw errors, the error messages are usually human-readable. if ``isort`` gives any errors, you can have it automatically correct the order of all imports by running ``isort --recursive intranet``. If the build fails because running ``scripts/format.sh`` resulted in changes, you can simply run ``./scripts/format.sh`` to fix your formatting. - -Imports -======= - -- Group imports in the following order: - #. Standard library imports - #. Third-party imports - #. Imports from Django - #. Local imports - -- Within these groups, place ``from ... import ...`` imports after ``import ...`` imports, and order imports alphabetically within *those* groups. - -- Avoid using ``from ... import *``. - -- Explicitly import each module used. - -- Use relative imports to avoid hardcoding a module's package name. This greatly improves portability and is useful when importing from another module in the current app. - -Examples --------- - -Standard library imports: - -.. code-block:: python - - from math import sqrt - from os.path import abspath - -Core Django imports: - -.. code-block:: python - - from django.db import models - -Third-party app imports: - -.. code-block:: python - - from django_extensions.db.models import TimeStampedModel - -Good: - -.. code-block:: python - - from .models import SomeModel # explicit relative import - from otherdjangoapp.models import OtherModel # absolute import - -Bad: - -.. code-block:: python - - # intranet/apps/users/views.py - from intranet.apps.users.models import MyModel # absolute import within same package - - -References -========== - -- `Google Python Style Guide `_. -- `Google HTML/CSS Style Guide `_. -- `Google Javascript Style Guide `_. -- `PEP8: Official Python Style Guide `_. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000000..564c2860c28 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +furo +myst-parser +sphinx-copybutton +sphinxcontrib-django diff --git a/docs/rtd-requirements.txt b/docs/rtd-requirements.txt deleted file mode 100644 index 71bbe37d0a4..00000000000 --- a/docs/rtd-requirements.txt +++ /dev/null @@ -1,68 +0,0 @@ -argon2-cffi==21.3.0 -autobahn==22.7.1 -Babel==2.10.3 -bcrypt==4.0.0 -beautifulsoup4==4.11.1 -bleach==5.0.1 -celery==5.2.7 -certifi==2024.07.04 -channels==3.0.5 -channels-redis==3.4.1 -contextlib2==21.6.0 -cryptography==42.0.4 -decorator==5.1.1 -Django==3.2.25 -django-cacheops==7.0.1 -django-cors-headers==3.13.0 -django-debug-toolbar==3.6.0 -django-extensions==3.2.0 -django-formtools==2.3 -django-inline-svg==0.1.1 -django-maintenance-mode==0.16.3 -django-oauth-toolkit==2.3.0 -django-pipeline==2.0.9 -django-prometheus==2.2.0 -django-redis-cache==3.0.1 -django-redis-sessions==0.6.2 -django-referrer-policy==1.0 -django-requestlogging-redux==1.2.1 -django-simple-history==3.1.1 -django-user-agents==0.4.0 -django-widget-tweaks==1.4.12 -djangorestframework==3.14.0 -docutils==0.19 -Fabric3==1.14.post1 -flower==1.2.0 -gunicorn==22.0.0 -hiredis==2.0.0 -ipython==8.10.0 -isort==5.12.0 -lxml==4.9.1 -objgraph==3.5.0 -pexpect==4.8.0 -prometheus-client==0.17.0 -psycopg2==2.9.9 -pycryptodome==3.19.1 -pyrankvote==2.0.5 -pysftp==0.2.9 -python-dateutil==2.8.2 -python-magic==0.4.27 -python-pam==2.0.2 -reportlab==3.6.13 -requests==2.32.0 -requests-oauthlib==1.3.1 -sentry-sdk==1.15.0 -setuptools-git==1.2 -six==1.16.0 -Sphinx==5.2.3 -sphinx-bootstrap-theme==0.8.1 -tblib==1.7.0 -vine==5.0.0 -xhtml2pdf==0.2.11 - -# Not direct dependencies, but need to be bumped for some reason -# (for example, bug or security fixes) -asgiref>=3.3.4 -pillow>=9.0.0 -tinycss2 -twisted>=21.7.0 diff --git a/docs/_static/custom.css b/docs/source/_static/custom.css similarity index 100% rename from docs/_static/custom.css rename to docs/source/_static/custom.css diff --git a/docs/favicon.ico b/docs/source/_static/favicon.ico similarity index 100% rename from docs/favicon.ico rename to docs/source/_static/favicon.ico diff --git a/docs/source/_static/logo-dark.svg b/docs/source/_static/logo-dark.svg new file mode 100644 index 00000000000..42b1477cb1c --- /dev/null +++ b/docs/source/_static/logo-dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/source/_static/logo-light.svg b/docs/source/_static/logo-light.svg new file mode 100644 index 00000000000..cfa12c9cc10 --- /dev/null +++ b/docs/source/_static/logo-light.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst new file mode 100644 index 00000000000..7ef38d10824 --- /dev/null +++ b/docs/source/_templates/autosummary/class.rst @@ -0,0 +1,34 @@ +{{ name | escape | underline}} + +Qualified name: ``{{ fullname | escape }}`` + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :show-inheritance: + :members: + :private-members: + + + {% block methods %} + {%- if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + :nosignatures: + {% for item in methods if item != '__init__' and item[0] != '_' and item not in inherited_members %} + ~{{ name }}.{{ item }} + {%- endfor %} + {%- endif %} + {%- endblock %} + + {% block attributes %} + {%- if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes if item[0] != '_' and item not in inherited_members %} + ~{{ name }}.{{ item }} + {%- endfor %} + {%- endif %} + {% endblock %} diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst new file mode 100644 index 00000000000..8aba97b3ba4 --- /dev/null +++ b/docs/source/_templates/autosummary/module.rst @@ -0,0 +1,52 @@ +{{ name | escape | underline }} + +.. currentmodule:: {{ fullname }} + +.. automodule:: {{ fullname }} + + {% block classes %} + {% if classes %} + .. rubric:: Classes + + .. autosummary:: + :toctree: . + :nosignatures: + {% for class in classes %} + {{ class }} + {% endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + {% for item in functions %} + .. autofunction:: {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} diff --git a/docs/architecture/index.rst b/docs/source/architecture/index.rst similarity index 100% rename from docs/architecture/index.rst rename to docs/source/architecture/index.rst diff --git a/docs/conf.py b/docs/source/conf.py similarity index 58% rename from docs/conf.py rename to docs/source/conf.py index ca745334770..2e84158f2bd 100644 --- a/docs/conf.py +++ b/docs/source/conf.py @@ -1,5 +1,3 @@ -# -*- coding: utf-8 -*- -# # TJ Intranet documentation build configuration file, created by # sphinx-quickstart on Wed Jan 7 14:37:16 2015. # @@ -15,42 +13,31 @@ import os import sys from datetime import datetime -from unittest import mock - -import sphinx_bootstrap_theme +from pathlib import Path -import django +# -- Add to sys.path ------------------------------------------------------ +ION_ROOT = Path(__file__).parent.parent.parent.resolve() +sys.path.insert(0, os.fspath(ION_ROOT)) -# 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. -# sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.viewcode", "sphinx.ext.napoleon", "djangodocs"] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix of source filenames. -source_suffix = ".rst" - -# The encoding of source files. -# source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = "index" - # General information about the project. project = "TJ Intranet" -copyright = "{}, TJ Intranet Development Team".format(datetime.now().year) +copyright = f"{datetime.now().year}, TJ Intranet Development Team" + +django_settings = "intranet.settings" + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.extlinks", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx_copybutton", + "myst_parser", + "sphinxcontrib_django", +] # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -62,100 +49,76 @@ release = "v3" if "GITHUB_RUN_NUMBER" in os.environ: - release += " (Build #{})".format(os.environ["GITHUB_RUN_NUMBER"]) + release += f" (Build #{os.environ['GITHUB_RUN_NUMBER']})" -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# language = None -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# today = '' -# Else, today_fmt is used as the format for a strftime call. -# today_fmt = '%B %d, %Y' +templates_path = ["_templates"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = [] -# The reST default role (used for this markup: `text`) to use for all -# documents. -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# add_module_names = True -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# show_authors = False +# We depend on sphinxcontrib_django for intersphinx mappings -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" +extlinks = { + "issue": ("https://github.com/tjcsl/ion/issues/%s", "issue %s"), + "pr": ("https://github.com/tjcsl/ion/pull/%s", "pr #%s"), +} +# warn hardcoded links +extlinks_detect_hardcoded_links = True -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] +source_suffix = [".rst", ".md"] -# If true, keep warnings as "system message" paragraphs in the built documents. -# keep_warnings = False # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "bootstrap" +html_theme = "furo" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - # Navigation bar title. (Default: ``project`` value) - # 'navbar_title': "", - # Tab name for entire site. (Default: "Site") - "navbar_site_name": "Topics", - "navbar_pagenav_name": "Section", - # Global TOC depth for "site" navbar tab. (Default: 1) - # Switching to -1 shows all levels. - "globaltoc_depth": 2, - # Include hidden TOCs in Site navbar? - # - # Note: If this is "false", you cannot have mixed ``:hidden:`` and - # non-hidden ``toctree`` directives in the same page, or else the build - # will break. - # - # Values: "true" (default) or "false" - "globaltoc_includehidden": "true", - # HTML navbar class (Default: "navbar") to attach to
element. - # For black navbar, do "navbar navbar-inverse" - "navbar_class": "navbar", - # Fix navigation bar to top of page? - # Values: "true" (default) or "false" - "navbar_fixed_top": "true", - # Location of link to source. - # Options are "nav" (default), "footer" or anything else to exclude. - "source_link_position": "footer", - # Bootswatch (http://bootswatch.com/) theme. - # - # Options are nothing with "" (default) or the name of a valid theme - # such as "amelia" or "cosmo". - # - # Note that this is served off CDN, so won't be available offline. - "bootswatch_theme": "pulse", - "bootstrap_version": "3", + "source_repository": "https://github.com/tjcsl/ion/", + "source_branch": "dev", + "source_directory": "docs/source/", + "light_logo": "logo-light.svg", + "dark_logo": "logo-dark.svg", + "sidebar_hide_name": True, + "light_css_variables": { + "color-content-foreground": "#000000", + "color-background-primary": "#ffffff", + "color-background-border": "#ffffff", + "color-sidebar-background": "#f8f9fb", + "color-brand-content": "#1c00e3", + "color-brand-primary": "#192bd0", + "color-link": "#c93434", + "color-link--hover": "#5b0000", + "color-inline-code-background": "#f6f6f6;", + "color-foreground-secondary": "#000", + }, + "dark_css_variables": { + "color-content-foreground": "#ffffffd9", + "color-background-primary": "#131416", + "color-background-border": "#303335", + "color-sidebar-background": "#1a1c1e", + "color-brand-content": "#2196f3", + "color-brand-primary": "#007fff", + "color-link": "#51ba86", + "color-link--hover": "#9cefc6", + "color-inline-code-background": "#262626", + "color-foreground-secondary": "#ffffffd9", + }, } -# Add any paths that contain custom themes here, relative to this directory. -html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() - # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -# html_title = None +html_title = "TJHSST Intranet" # A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None +html_short_title = "Ion" # The name of an image file (relative to this directory) to place at the top # of the sidebar. @@ -294,11 +257,6 @@ # If true, do not generate a @detailmenu in the "Top" node's menu. # texinfo_no_detailmenu = False -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = { - "python": ("https://docs.python.org/3", None), - "django": ("https://docs.djangoproject.com/en/dev", "https://docs.djangoproject.com/en/dev/_objects/"), -} autodoc_inherit_docstrings = False @@ -314,28 +272,6 @@ napoleon_use_param = True napoleon_use_rtype = True -# -- Django Setup ------------------------------------------------------------- - -# add project root -sys.path.append(os.path.dirname(os.path.dirname(__file__))) - -os.environ.setdefault("DJANGO_SETTINGS_MODULE", "intranet.settings") - -# Don't spin up a ldap server when building docs. -sys.modules["ldap_test"] = mock.MagicMock() - -# Django docs -sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext"))) - -django.setup() - - -def skip(app, what, name, obj, skip, options): - """Methods to skip when generating documentation from docstrings.""" - if name in ("__weakref__", "__dict__", "base_fields", "media", "history_object"): - return True - return skip - - -def setup(app): - app.connect("autodoc-skip-member", skip) +napoleon_custom_sections = [ + ("WIDGETS", "params_style"), +] diff --git a/CONTRIBUTING.md b/docs/source/developing/contributing.md similarity index 78% rename from CONTRIBUTING.md rename to docs/source/developing/contributing.md index c0217802820..cd4d039bf37 100644 --- a/CONTRIBUTING.md +++ b/docs/source/developing/contributing.md @@ -8,13 +8,13 @@ If you are a TJHSST student, you can join the `#ion` channel on the [TJ CSL Slac - Please use the templates. If none of them is a perfect match, choose the closest one. ## Security Vulnerabilities & Responsible Disclosure -Please see [our security policy](SECURITY.md). Do not report security vulnerabilities in the public issue tracker. +Please see [our security policy](#security-policy). Do not report security vulnerabilities in the public issue tracker. ## Pull Requests - All PRs should target `dev`, not `master`. - If the change is anything more than a simple typo or a fairly obvious fix, please [set up a development environment](docs/setup/vagrant.rst) and test the change there before submitting a PR. -- It is strongly recommended that you [run `flake8`, `pylint`, `isort`, `scripts/format.sh`](docs/developing/styleguide.rst#what-is-enforced-in-the-build), and [the test suite](docs/developing/testing.rst#running-tests) to ensure that the build will pass. Please also read the entire [style guide](docs/developing/styleguide.rst). -- Please read [Formatting commit messages](docs/developing/howto.rst#formatting-commit-messages). +- It is strongly recommended that you [run `pre-commit`](#pre_commit), and [the test suite](#running-tests) to ensure that the build will pass. Please also read the entire [style guide](styleguide.rst). +- Please read [Formatting commit messages](#formatting_commits). - If your PR closes an issue, include "Closes #XXX" or similar in the messages of the commits that close each issue so the issues will be [automatically closed](https://help.github.com/en/articles/closing-issues-using-keywords) when the commits are merged into `master`. Note that including this text in your PR's description will have no effect because the PR will be merged into `dev`, not `master`, so GitHub does not close the issue. You must add the auto-closing keywords to the *commit* messages. - Keep each commit/PR minimal. diff --git a/docs/developing/eighth-models.rst b/docs/source/developing/eighth-models.rst similarity index 100% rename from docs/developing/eighth-models.rst rename to docs/source/developing/eighth-models.rst diff --git a/docs/developing/howto.rst b/docs/source/developing/howto.rst similarity index 75% rename from docs/developing/howto.rst rename to docs/source/developing/howto.rst index 9220a86ef04..e13a5c54669 100644 --- a/docs/developing/howto.rst +++ b/docs/source/developing/howto.rst @@ -5,31 +5,40 @@ How to do Ion development Formatting your code ==================== -You can run ``./scripts/format.sh`` to automatically format your Python code to adhere to PEP8 standards. +You can run ``pre-commit run --all-files`` to automatically format your Python code to adhere to PEP8 standards. Updating the dev branch ======================= -- git fetch --all -- git checkout dev -- git pull origin dev (note that if dev has been rebased, this may cause a conflict) +- ``git fetch --all`` +- ``git checkout dev`` +- ``git pull origin dev`` (note that if dev has been rebased, this may cause a conflict) - if dev has been rebased, make *absolutely* sure that you don't have any local changes - and run git reset --hard origin/dev this *will* destroy any local changes you have made to dev. -- git push + and run ``git reset --hard origin/dev`` + + .. danger:: + + This *will* destroy any local changes you have made to ``dev``. + +- ``git push`` Fixing build ============ -You can run ``./deploy`` to fix or find most of your build problems. If you add a new file, you may need to run ``./setup.py egg_info``. +You can run ``./deploy`` to fix or find most of your build problems. Viewing documentation locally ============================= -You can view the documentation locally by running the commands below in the virtual machine. +You can view the documentation locally by running:: + + make html + +and then opening the file ``build/html/index.html`` in your browser. + -- ./scripts/build_docs.sh -- cd build/sphinx/html -- python -m http.server 8080 + +.. _formatting_commits: Formatting commit messages ========================== @@ -37,7 +46,9 @@ Formatting commit messages Effective June 2019, the Ion team uses the `Conventional Commit specification `_ to format commit messages. This means that all commit messages should be structured as follows + .. code-block:: text + [optional scope]: [optional body] @@ -58,7 +69,9 @@ The types that we use are: - ``test``: Adding missing tests or correcting existing tests For example, if a commit adds a new feature to the ``emailfwd`` app, a good commit message would be: + .. code-block:: text + feat(emailfwd): add email confirmation functionality Fixes #1 diff --git a/docs/developing/index.rst b/docs/source/developing/index.rst similarity index 85% rename from docs/developing/index.rst rename to docs/source/developing/index.rst index deedcd3e2a6..9935e3ddc09 100644 --- a/docs/developing/index.rst +++ b/docs/source/developing/index.rst @@ -3,6 +3,7 @@ Developing for Intranet *********************** .. toctree:: + :maxdepth: 2 :glob: * diff --git a/docs/developing/oauth.rst b/docs/source/developing/oauth.rst similarity index 100% rename from docs/developing/oauth.rst rename to docs/source/developing/oauth.rst diff --git a/docs/developing/requirements.rst b/docs/source/developing/requirements.rst similarity index 100% rename from docs/developing/requirements.rst rename to docs/source/developing/requirements.rst diff --git a/docs/source/developing/styleguide.rst b/docs/source/developing/styleguide.rst new file mode 100644 index 00000000000..3221813fa02 --- /dev/null +++ b/docs/source/developing/styleguide.rst @@ -0,0 +1,96 @@ +****************** +Coding Style Guide +****************** + +Follow `PEP8 `_ (the official style guide for Python). +However, if you want, you can use your own personal style guide, and then use ``pre-commit`` to format before committing. + +.. caution:: + + The CI will fail if the code is not formatted according to ``pre-commit``, so it's recommendded to use ``pre-commit``. + +Main points +=========== + +- Indent using 4 spaces. +- Use underscores in favor of camel case for all names. For classes use PascalCase. +- Limit the line length of docstrings or comments to 72 characters. +- Separate top-level functions and class definitions with two blank lines. +- Separate method definitions inside a class with a single blank line. +- Use two spaces before inline comments and one space between the pound sign and comment. +- Use a plugin for your text editor to check for/remind you of PEP8 conventions. +- When in doubt, running ``pre-commit run --all-files`` will fix a lot of things. +- Capitalize and punctuate comments and Git commit messages properly. + + +.. _pre_commit: + +What is enforced in the build +============================= + +At the time of this writing, the GitHub Actions build runs the following commands: + +.. code-block:: bash + + pre-commit run --all-files + + +It will fail if it has to make changes to the code. + +The ``pre-commit`` config should run ``ruff``, ``codespell``, and some other linters. Most of the time it should autofix problems, +but there may be some linting errors that require manual intervention. + +Imports +======= + +- Avoid using ``from ... import *``. + +- Explicitly import each module used. + +- Use relative imports to avoid hardcoding a module's package name. This greatly improves portability and is useful when importing + from another module in the current app. + +Examples +-------- + +Standard library imports: + +.. code-block:: python + + from math import sqrt + from os.path import abspath + +Core Django imports: + +.. code-block:: python + + from django.db import models + +Third-party app imports: + +.. code-block:: python + + from django_extensions.db.models import TimeStampedModel + +Good: + +.. code-block:: python + + from .models import SomeModel # explicit relative import + from otherdjangoapp.models import OtherModel # absolute import + +Bad: + +.. code-block:: python + + # intranet/apps/users/views.py + from intranet.apps.users.models import MyModel # absolute import within same package + + +References +========== + +- `Google Python Style Guide `_. +- `Google HTML/CSS Style Guide `_. +- `Google Javascript Style Guide `_. +- `PEP8: Official Python Style Guide `_. diff --git a/docs/developing/testing.rst b/docs/source/developing/testing.rst similarity index 81% rename from docs/developing/testing.rst rename to docs/source/developing/testing.rst index 5896d7181d4..a4335c1a5ea 100644 --- a/docs/developing/testing.rst +++ b/docs/source/developing/testing.rst @@ -9,6 +9,8 @@ Unit Tests For most modules, the unit tests go in ``intranet/apps//tests.py``. Currently, the sole exception is ``eighth``, where tests are broken out into several different files under ``intranet/apps/eighth/tests/``. Testing functionality that is useful for multiple tests can be found in ``intranet/test``. +.. _running-tests: + Running Tests ============= @@ -35,7 +37,13 @@ Looking at pre-existing tests can give you a good idea how to structure your tes Every test should include comments that explain, almost in narrative form, what the test is doing and what the expected results are. -Generally, there are two ways that you test Ion's code. These are not comprehensive, but should work for most cases. The first is calling methods directly; the second is making a GET or POST request to the view that you are interested in testing. The best tests utilize both. After you do either/both of these to call the code, you should use assertions to see if the code behaved as expected. A list of assertion options can be found `here `. A useful tool for making requests to the view is ``self.client``. More documentation on that can be found `here `_. Alternatively, just search through Ion's testing files for examples of using `self.client`. +Generally, there are two ways that you test Ion's code. These are not comprehensive, but should work for most cases. +The first is calling methods directly; the second is making a GET or POST request to the view that you are interested in testing. +The best tests utilize both. After you do either/both of these to call the code, you should use assertions to see if the code behaved as expected. +A list of assertion options can be found `here `_. +A useful tool for making requests to the view is ``self.client``. More documentation on that can be found +`here `_. Alternatively, just search through Ion's +testing files for examples of using `self.client`. Good Testing Examples ===================== diff --git a/docs/developing/updates.rst b/docs/source/developing/updates.rst similarity index 63% rename from docs/developing/updates.rst rename to docs/source/developing/updates.rst index ca2a314b2a7..43e2a6fda9a 100644 --- a/docs/developing/updates.rst +++ b/docs/source/developing/updates.rst @@ -5,18 +5,18 @@ Keeping things up-to-date Vendored Libraries ================== -- `CKEditor _` -- `datetimepicker _` +- `CKEditor `_ +- `datetimepicker `_ - jQuery-UI: *Note: This has very specific CSL customizations)* -- `Messenger _` -- `selectize _` -- `sortable _` +- `Messenger `_ +- `selectize `_ +- `sortable `_ Updating Top-level Requirements ================================ -If any commit changes the direct dependencies of Ion, you must update `the requirements documentation`_ to reflect the changes to Ion's dependencies. That page is organized into sections for each dependency, with a line for the package's source URL, a general description of the package, the usage of the package in Ion, and the package's license. +If any commit changes the direct dependencies of Ion, you must update `the requirements documentation `_ to reflect the changes to Ion's dependencies. That page is organized into sections for each dependency, with a line for the package's source URL, a general description of the package, the usage of the package in Ion, and the package's license. For example, here is a valid section: @@ -36,6 +36,7 @@ Additional lines may be added to identify needed actions regarding the package. Requirements for Dependencies ============================== -**All** dependencies to Ion must be licensed under an `OSI-approved open source license `_. The use of the package must be compatible with the terms of the GNU General Public License v2 (or later version). +**All** dependencies to Ion must be licensed under an `OSI-approved open source license `_. +The use of the package must be compatible with the terms of the GNU General Public License v2 (or later version). **All** direct dependencies to Ion must be reported in the requirements documentation. diff --git a/USERNAMES.md b/docs/source/developing/usernames.md similarity index 100% rename from USERNAMES.md rename to docs/source/developing/usernames.md diff --git a/docs/index.rst b/docs/source/index.rst similarity index 98% rename from docs/index.rst rename to docs/source/index.rst index e23cae37882..d06bbdf66b0 100644 --- a/docs/index.rst +++ b/docs/source/index.rst @@ -17,7 +17,7 @@ Contents setup/index architecture/index developing/index - sourcedoc/modules + reference_index Setup ----- diff --git a/docs/source/reference_index.rst b/docs/source/reference_index.rst new file mode 100644 index 00000000000..d65f3296815 --- /dev/null +++ b/docs/source/reference_index.rst @@ -0,0 +1,48 @@ +############### +Reference Index +############### + +This is a collection of autogenerated documentation about Ion. +It's meant to be a reference - feel free to check it out! + +.. toctree:: + :maxdepth: 1 + + reference_index/announcements + reference_index/api + reference_index/auth + reference_index/bus + reference_index/cslapps + reference_index/customthemes + reference_index/dashboard + reference_index/eighth + reference_index/emailfwd + reference_index/emerg + reference_index/enrichment + reference_index/error + reference_index/events + reference_index/features + reference_index/feedback + reference_index/files + reference_index/groups + reference_index/itemreg + reference_index/logs + reference_index/lostfound + reference_index/middleware + reference_index/nomination + reference_index/notifications + reference_index/oauth + reference_index/parking + reference_index/polls + reference_index/preferences + reference_index/printing + reference_index/schedule + reference_index/search + reference_index/seniors + reference_index/sessionmgmt + reference_index/signage + reference_index/templatetags + reference_index/testing + reference_index/users + reference_index/utils + reference_index/welcome diff --git a/docs/source/reference_index/announcements.rst b/docs/source/reference_index/announcements.rst new file mode 100644 index 00000000000..2543b48da75 --- /dev/null +++ b/docs/source/reference_index/announcements.rst @@ -0,0 +1,15 @@ +############# +Announcements +############# + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~announcements.forms + ~announcements.models + ~announcements.notifications + ~announcements.serializers + ~announcements.views diff --git a/docs/source/reference_index/api.rst b/docs/source/reference_index/api.rst new file mode 100644 index 00000000000..93ccdc3706d --- /dev/null +++ b/docs/source/reference_index/api.rst @@ -0,0 +1,12 @@ +### +Api +### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~api.views + ~api.authentication diff --git a/docs/source/reference_index/auth.rst b/docs/source/reference_index/auth.rst new file mode 100644 index 00000000000..7ad711d001b --- /dev/null +++ b/docs/source/reference_index/auth.rst @@ -0,0 +1,17 @@ +#### +Auth +#### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~auth.backends + ~auth.decorators + ~auth.forms + ~auth.management.commands.grant_admin + ~auth.rest_permissions + ~auth.signals + ~auth.views diff --git a/docs/source/reference_index/bus.rst b/docs/source/reference_index/bus.rst new file mode 100644 index 00000000000..c8579ccec6b --- /dev/null +++ b/docs/source/reference_index/bus.rst @@ -0,0 +1,16 @@ +### +Bus +### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~bus.models + ~bus.views + ~bus.consumers + ~bus.serializers + ~bus.management.commands.import_routes + ~bus.management.commands.reset_routes diff --git a/docs/source/reference_index/cslapps.rst b/docs/source/reference_index/cslapps.rst new file mode 100644 index 00000000000..14a5368c079 --- /dev/null +++ b/docs/source/reference_index/cslapps.rst @@ -0,0 +1,13 @@ +####### +Cslapps +####### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~cslapps.models + ~cslapps.views + ~cslapps.management.commands.dev_create_cslapps diff --git a/docs/source/reference_index/customthemes.rst b/docs/source/reference_index/customthemes.rst new file mode 100644 index 00000000000..d6a4e8cb28c --- /dev/null +++ b/docs/source/reference_index/customthemes.rst @@ -0,0 +1,11 @@ +############ +Customthemes +############ + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~customthemes.views \ No newline at end of file diff --git a/docs/source/reference_index/dashboard.rst b/docs/source/reference_index/dashboard.rst new file mode 100644 index 00000000000..af087c5634a --- /dev/null +++ b/docs/source/reference_index/dashboard.rst @@ -0,0 +1,11 @@ +######### +Dashboard +######### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~dashboard.views \ No newline at end of file diff --git a/docs/source/reference_index/dataimport.rst b/docs/source/reference_index/dataimport.rst new file mode 100644 index 00000000000..9cc673be968 --- /dev/null +++ b/docs/source/reference_index/dataimport.rst @@ -0,0 +1,9 @@ +########## +Dataimport +########## + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + diff --git a/docs/source/reference_index/django.rst b/docs/source/reference_index/django.rst new file mode 100644 index 00000000000..c8231e3f8f6 --- /dev/null +++ b/docs/source/reference_index/django.rst @@ -0,0 +1,9 @@ +###### +Django +###### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + diff --git a/docs/source/reference_index/eighth.rst b/docs/source/reference_index/eighth.rst new file mode 100644 index 00000000000..f9b30880b53 --- /dev/null +++ b/docs/source/reference_index/eighth.rst @@ -0,0 +1,38 @@ +###### +Eighth +###### + +.. currentmodule:: intranet.apps + +You can find the views in :doc:`eighth_views`. + +.. toctree:: + :hidden: + + eighth_views + +.. autosummary:: + :toctree: ../reference + + + ~eighth.context_processors + ~eighth.models + ~eighth.notifications + ~eighth.tasks + +It also comes with several management commands: + +.. autosummary:: + :toctree: ../reference + + ~eighth.management.commands.absence_email + ~eighth.management.commands.delete_duplicate_signups + ~eighth.management.commands.dev_create_blocks + ~eighth.management.commands.dev_generate_signups + ~eighth.management.commands.find_duplicates + ~eighth.management.commands.generate_similarities + ~eighth.management.commands.generate_statistics + ~eighth.management.commands.remove_withdrawn_students + ~eighth.management.commands.signup_statistics + ~eighth.management.commands.signup_status_email + ~eighth.management.commands.update_counselors diff --git a/docs/source/reference_index/eighth_views.rst b/docs/source/reference_index/eighth_views.rst new file mode 100644 index 00000000000..74abcca825d --- /dev/null +++ b/docs/source/reference_index/eighth_views.rst @@ -0,0 +1,17 @@ +############ +Eighth Views +############ + +.. currentmodule:: intranet.apps.eighth + +.. autosummary:: + :toctree: ../reference + + + ~views.activities + ~views.api + ~views.attendance + ~views.monitoring + ~views.profile + ~views.routers + ~views.signup diff --git a/docs/source/reference_index/emailfwd.rst b/docs/source/reference_index/emailfwd.rst new file mode 100644 index 00000000000..ee9b63c3112 --- /dev/null +++ b/docs/source/reference_index/emailfwd.rst @@ -0,0 +1,12 @@ +######## +Emailfwd +######## + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~emailfwd.models + ~emailfwd.forms diff --git a/docs/source/reference_index/emerg.rst b/docs/source/reference_index/emerg.rst new file mode 100644 index 00000000000..14d24685fef --- /dev/null +++ b/docs/source/reference_index/emerg.rst @@ -0,0 +1,11 @@ +##### +Emerg +##### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~emerg.views \ No newline at end of file diff --git a/docs/source/reference_index/enrichment.rst b/docs/source/reference_index/enrichment.rst new file mode 100644 index 00000000000..92ad208afe9 --- /dev/null +++ b/docs/source/reference_index/enrichment.rst @@ -0,0 +1,13 @@ +########## +Enrichment +########## + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~enrichment.models + ~enrichment.views + ~enrichment.forms \ No newline at end of file diff --git a/docs/source/reference_index/error.rst b/docs/source/reference_index/error.rst new file mode 100644 index 00000000000..4abcd286755 --- /dev/null +++ b/docs/source/reference_index/error.rst @@ -0,0 +1,11 @@ +##### +Error +##### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~error.views \ No newline at end of file diff --git a/docs/source/reference_index/events.rst b/docs/source/reference_index/events.rst new file mode 100644 index 00000000000..3e5f76c544b --- /dev/null +++ b/docs/source/reference_index/events.rst @@ -0,0 +1,13 @@ +###### +Events +###### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~events.models + ~events.views + ~events.forms \ No newline at end of file diff --git a/docs/source/reference_index/features.rst b/docs/source/reference_index/features.rst new file mode 100644 index 00000000000..9a770630f19 --- /dev/null +++ b/docs/source/reference_index/features.rst @@ -0,0 +1,12 @@ +######## +Features +######## + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~features.models + ~features.views \ No newline at end of file diff --git a/docs/source/reference_index/feedback.rst b/docs/source/reference_index/feedback.rst new file mode 100644 index 00000000000..5e3cc30c81a --- /dev/null +++ b/docs/source/reference_index/feedback.rst @@ -0,0 +1,13 @@ +######## +Feedback +######## + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~feedback.models + ~feedback.views + ~feedback.forms \ No newline at end of file diff --git a/docs/source/reference_index/files.rst b/docs/source/reference_index/files.rst new file mode 100644 index 00000000000..dbd7077dc86 --- /dev/null +++ b/docs/source/reference_index/files.rst @@ -0,0 +1,13 @@ +##### +Files +##### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~files.models + ~files.views + ~files.forms \ No newline at end of file diff --git a/docs/source/reference_index/groups.rst b/docs/source/reference_index/groups.rst new file mode 100644 index 00000000000..61ea1684408 --- /dev/null +++ b/docs/source/reference_index/groups.rst @@ -0,0 +1,13 @@ +###### +Groups +###### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~groups.models + ~groups.views + ~groups.forms \ No newline at end of file diff --git a/docs/source/reference_index/itemreg.rst b/docs/source/reference_index/itemreg.rst new file mode 100644 index 00000000000..4812472ecdd --- /dev/null +++ b/docs/source/reference_index/itemreg.rst @@ -0,0 +1,13 @@ +####### +Itemreg +####### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~itemreg.models + ~itemreg.views + ~itemreg.forms \ No newline at end of file diff --git a/docs/source/reference_index/logs.rst b/docs/source/reference_index/logs.rst new file mode 100644 index 00000000000..b75bc9d1b3a --- /dev/null +++ b/docs/source/reference_index/logs.rst @@ -0,0 +1,13 @@ +#### +Logs +#### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~logs.models + ~logs.views + ~logs.forms \ No newline at end of file diff --git a/docs/source/reference_index/lostfound.rst b/docs/source/reference_index/lostfound.rst new file mode 100644 index 00000000000..affcba456aa --- /dev/null +++ b/docs/source/reference_index/lostfound.rst @@ -0,0 +1,13 @@ +######### +Lostfound +######### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~lostfound.models + ~lostfound.views + ~lostfound.forms \ No newline at end of file diff --git a/docs/source/reference_index/middleware.rst b/docs/source/reference_index/middleware.rst new file mode 100644 index 00000000000..71dec9ae536 --- /dev/null +++ b/docs/source/reference_index/middleware.rst @@ -0,0 +1,20 @@ +########## +Middleware +########## + +.. currentmodule:: intranet + +.. autosummary:: + :toctree: ../reference + + + middleware.access_log + middleware.ajax + middleware.dark_mode + middleware.monitoring + middleware.same_origin + middleware.session_management + middleware.templates + middleware.threadlocals + middleware.traceback + middleware.url_slashes diff --git a/docs/source/reference_index/nomination.rst b/docs/source/reference_index/nomination.rst new file mode 100644 index 00000000000..2c56b5a3f76 --- /dev/null +++ b/docs/source/reference_index/nomination.rst @@ -0,0 +1,12 @@ +########## +Nomination +########## + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~nomination.models + ~nomination.views \ No newline at end of file diff --git a/docs/source/reference_index/notifications.rst b/docs/source/reference_index/notifications.rst new file mode 100644 index 00000000000..b2349533c08 --- /dev/null +++ b/docs/source/reference_index/notifications.rst @@ -0,0 +1,13 @@ +############# +Notifications +############# + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~notifications.emails + ~notifications.models + ~notifications.views diff --git a/docs/source/reference_index/oauth.rst b/docs/source/reference_index/oauth.rst new file mode 100644 index 00000000000..15f15122197 --- /dev/null +++ b/docs/source/reference_index/oauth.rst @@ -0,0 +1,12 @@ +##### +Oauth +##### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~oauth.models + ~oauth.views \ No newline at end of file diff --git a/docs/source/reference_index/parking.rst b/docs/source/reference_index/parking.rst new file mode 100644 index 00000000000..a75d0b1f9a3 --- /dev/null +++ b/docs/source/reference_index/parking.rst @@ -0,0 +1,13 @@ +####### +Parking +####### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~parking.models + ~parking.views + ~parking.forms \ No newline at end of file diff --git a/docs/source/reference_index/polls.rst b/docs/source/reference_index/polls.rst new file mode 100644 index 00000000000..6d3f9002ce9 --- /dev/null +++ b/docs/source/reference_index/polls.rst @@ -0,0 +1,13 @@ +##### +Polls +##### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~polls.models + ~polls.views + ~polls.forms \ No newline at end of file diff --git a/docs/source/reference_index/preferences.rst b/docs/source/reference_index/preferences.rst new file mode 100644 index 00000000000..a5cfca7310a --- /dev/null +++ b/docs/source/reference_index/preferences.rst @@ -0,0 +1,13 @@ +########### +Preferences +########### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~preferences.fields + ~preferences.views + ~preferences.forms diff --git a/docs/source/reference_index/printing.rst b/docs/source/reference_index/printing.rst new file mode 100644 index 00000000000..59e9ad56a91 --- /dev/null +++ b/docs/source/reference_index/printing.rst @@ -0,0 +1,13 @@ +######## +Printing +######## + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~printing.models + ~printing.views + ~printing.forms \ No newline at end of file diff --git a/docs/source/reference_index/schedule.rst b/docs/source/reference_index/schedule.rst new file mode 100644 index 00000000000..8e1e51bb825 --- /dev/null +++ b/docs/source/reference_index/schedule.rst @@ -0,0 +1,13 @@ +######## +Schedule +######## + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~schedule.models + ~schedule.views + ~schedule.forms \ No newline at end of file diff --git a/docs/source/reference_index/search.rst b/docs/source/reference_index/search.rst new file mode 100644 index 00000000000..64e0efa38df --- /dev/null +++ b/docs/source/reference_index/search.rst @@ -0,0 +1,11 @@ +###### +Search +###### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~search.views \ No newline at end of file diff --git a/docs/source/reference_index/seniors.rst b/docs/source/reference_index/seniors.rst new file mode 100644 index 00000000000..5ba1cec7424 --- /dev/null +++ b/docs/source/reference_index/seniors.rst @@ -0,0 +1,13 @@ +####### +Seniors +####### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~seniors.models + ~seniors.views + ~seniors.forms \ No newline at end of file diff --git a/docs/source/reference_index/sessionmgmt.rst b/docs/source/reference_index/sessionmgmt.rst new file mode 100644 index 00000000000..5d7dff89b7e --- /dev/null +++ b/docs/source/reference_index/sessionmgmt.rst @@ -0,0 +1,13 @@ +########### +Sessionmgmt +########### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~sessionmgmt.helpers + ~sessionmgmt.models + ~sessionmgmt.views diff --git a/docs/source/reference_index/signage.rst b/docs/source/reference_index/signage.rst new file mode 100644 index 00000000000..f3c91635689 --- /dev/null +++ b/docs/source/reference_index/signage.rst @@ -0,0 +1,15 @@ +####### +Signage +####### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~signage.consumers + ~signage.forms + ~signage.models + ~signage.pages + ~signage.views diff --git a/docs/source/reference_index/templatetags.rst b/docs/source/reference_index/templatetags.rst new file mode 100644 index 00000000000..ccf1128f091 --- /dev/null +++ b/docs/source/reference_index/templatetags.rst @@ -0,0 +1,20 @@ +############ +Templatetags +############ + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~templatetags.forms + ~templatetags.dates + ~templatetags.dictionaries + ~templatetags.form_field + ~templatetags.forms + ~templatetags.math + ~templatetags.newtab_links + ~templatetags.paginate + ~templatetags.paginate + ~templatetags.strings diff --git a/docs/source/reference_index/testing.rst b/docs/source/reference_index/testing.rst new file mode 100644 index 00000000000..b764ed2e5d1 --- /dev/null +++ b/docs/source/reference_index/testing.rst @@ -0,0 +1,11 @@ +##### +Tests +##### + +.. currentmodule:: intranet + +.. autosummary:: + :toctree: ../reference + + + ~test.ion_test diff --git a/docs/source/reference_index/users.rst b/docs/source/reference_index/users.rst new file mode 100644 index 00000000000..9050b80af8f --- /dev/null +++ b/docs/source/reference_index/users.rst @@ -0,0 +1,15 @@ +##### +Users +##### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~users.models + ~users.views + ~users.forms + ~users.api + ~users.renderers diff --git a/docs/source/reference_index/utils.rst b/docs/source/reference_index/utils.rst new file mode 100644 index 00000000000..74e9602baf8 --- /dev/null +++ b/docs/source/reference_index/utils.rst @@ -0,0 +1,19 @@ +############## +Intranet Utils +############## + +.. currentmodule:: intranet + +.. autosummary:: + :toctree: ../reference + + + ~utils.admin_helpers + ~utils.cache + ~utils.date + ~utils.deletion + ~utils.helpers + ~utils.html + ~utils.locking + ~utils.serialization + ~utils.session diff --git a/docs/source/reference_index/welcome.rst b/docs/source/reference_index/welcome.rst new file mode 100644 index 00000000000..1cda3e594f7 --- /dev/null +++ b/docs/source/reference_index/welcome.rst @@ -0,0 +1,11 @@ +####### +Welcome +####### + +.. currentmodule:: intranet.apps + +.. autosummary:: + :toctree: ../reference + + + ~welcome.views \ No newline at end of file diff --git a/SECURITY.md b/docs/source/security.md similarity index 97% rename from SECURITY.md rename to docs/source/security.md index f29859d8781..88df92648d8 100644 --- a/SECURITY.md +++ b/docs/source/security.md @@ -1,3 +1,4 @@ +(security-policy)= # Security Policy ## Reporting a Vulnerability diff --git a/docs/setup/index.rst b/docs/source/setup/index.rst similarity index 74% rename from docs/setup/index.rst rename to docs/source/setup/index.rst index 14a150201ad..45af3f05834 100644 --- a/docs/setup/index.rst +++ b/docs/source/setup/index.rst @@ -2,6 +2,7 @@ Setup ***** .. toctree:: + :maxdepth: 2 :glob: * diff --git a/docs/setup/server.rst b/docs/source/setup/server.rst similarity index 100% rename from docs/setup/server.rst rename to docs/source/setup/server.rst diff --git a/SETUP.md b/docs/source/setup/setup.md similarity index 100% rename from SETUP.md rename to docs/source/setup/setup.md diff --git a/intranet/apps/cslapps/models.py b/intranet/apps/cslapps/models.py index 4f3ea8d922c..1d4241b7f33 100644 --- a/intranet/apps/cslapps/models.py +++ b/intranet/apps/cslapps/models.py @@ -14,22 +14,7 @@ def visible_to_user(self, user): class App(models.Model): - """ - Represents an app maintained by the CSL. - Attributes: - name (str): The name of the app. - description (str): A description of the app. - order (int): The order in which the app should be displayed. - oauth_application (:obj:`CSLApplication`): The OAuth application associated with the app, if any. - auth_url (str): The URL to the app's authentication page (preferably, if available, using Ion OAuth). - url (str): The URL to the app. - image_url (str): The URL to the image icon for the app. - html_icon (str): HTML for the icon of the app, can be used for things like font awesome icons. - WARNING: this is rendered as safe. Do not allow untrusted content here. - invert_image_color_for_dark_mode (bool): Whether or not to invert the image color for dark mode. - Set to true if the image is a mostly dark color, which will require it to be inverted to appear on dark mode. - groups_visible (:obj:`list` of :obj:`Group`): Groups that can access this app. - """ + """Represents an app maintained by TJ CSL.""" objects = AppManager() diff --git a/intranet/apps/dashboard/views.py b/intranet/apps/dashboard/views.py index b2400653b8f..237537b26bd 100644 --- a/intranet/apps/dashboard/views.py +++ b/intranet/apps/dashboard/views.py @@ -196,6 +196,7 @@ def get_prerender_url(request): def get_announcements_list(request, context): """ An announcement will be shown if: + * It is not expired * unless ?show_expired=1 @@ -211,6 +212,7 @@ def get_announcements_list(request, context): * ...unless ?show_all=1 An event will be shown if: + * It is not expired * unless ?show_expired=1 @@ -265,10 +267,7 @@ def announcements_sorting_key(item): def paginate_announcements_list(request, context, items): - """ - Paginate ``items`` in groups of 15 - - """ + """Paginate ``items`` in groups of 15""" DEFAULT_PAGE_NUM = 1 if request.GET.get("page", "INVALID").isdigit(): @@ -304,6 +303,7 @@ def get_tjstar_mapping(user): def add_widgets_context(request, context): """ WIDGETS: + * Eighth signup (STUDENT) * Eighth attendance (TEACHER or ADMIN) * Enrichment activities (ALL if enrichment activity today) diff --git a/scripts/build_docs.sh b/scripts/build_docs.sh deleted file mode 100755 index b9f6c5141ea..00000000000 --- a/scripts/build_docs.sh +++ /dev/null @@ -1,6 +0,0 @@ -set -e -echo "Building docs..." -excludes="intranet/settings/secret.py intranet/urls.py intranet/apps/*/migrations" -sphinx-apidoc -f -o build/.tmp intranet $excludes -rsync --checksum build/.tmp/*.rst docs/sourcedoc/ -sphinx-build -WT -j auto docs -d build/sphinx/doctrees build/sphinx/html diff --git a/scripts/build_sources.sh b/scripts/build_sources.sh deleted file mode 100755 index 09674a87a0f..00000000000 --- a/scripts/build_sources.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash - -# This script is now obsolete due to the use of pyproject.toml. It is kept for future reference. -cd "$(dirname -- "$(readlink -f -- "$0")")/.." -./setup.py egg_info diff --git a/scripts/check.sh b/scripts/check.sh deleted file mode 100755 index 1f03088911e..00000000000 --- a/scripts/check.sh +++ /dev/null @@ -1,21 +0,0 @@ -#!/bin/bash -# Convenience script that runs format and lint scripts. - -set -e - -echo "Formatting..." -./scripts/format.sh -./scripts/static_templates_format.sh -echo - -echo "Validating commit messages..." -./scripts/validate-commit-messages.py $(git rev-parse HEAD~1) -echo - -if [ "$1" = "--lint" ]; then - echo "Linting..." - ./scripts/lint.sh - echo -fi - -echo "Done!" \ No newline at end of file diff --git a/scripts/format.sh b/scripts/format.sh deleted file mode 100755 index 9cb5206a8bd..00000000000 --- a/scripts/format.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/bin/bash -cd "$(dirname -- "$(dirname -- "$(readlink -f "$0")")")" - -black . && autopep8 --in-place --recursive -j -1 . && isort -j 4 . diff --git a/scripts/lint.sh b/scripts/lint.sh deleted file mode 100755 index e793607225b..00000000000 --- a/scripts/lint.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/bin/bash - -flake8 --max-line-length 150 --exclude=*/migrations/* intranet/ scripts/ docs/ *.py -pylint --jobs=8 --disable=fixme,broad-exception-caught,broad-exception-raised,unsupported-binary-operation,global-statement,attribute-defined-outside-init,cyclic-import,consider-using-f-string --django-settings-module=intranet.settings intranet/ diff --git a/scripts/push_docs.sh b/scripts/push_docs.sh index b6f5ff654a4..90c9894ca94 100755 --- a/scripts/push_docs.sh +++ b/scripts/push_docs.sh @@ -9,7 +9,7 @@ git config --global user.name "GitHub Actions" git clone --depth=50 --branch=gh-pages "https://${GH_TOKEN}@github.com/tjcsl/ion.git" gh-pages rm -rf gh-pages/* cd gh-pages -cp -R ../build/sphinx/html/* . +cp -R ../docs/build/sphinx/html/* . git add -A . latest=$(git log -1 --pretty=%s|sed "s/GitHub Actions build \([0-9]\+\)/\1/") git commit -m "GitHub Actions build $GITHUB_RUN_NUMBER" diff --git a/scripts/static_templates_format.sh b/scripts/static_templates_format.sh deleted file mode 100755 index b4303594d92..00000000000 --- a/scripts/static_templates_format.sh +++ /dev/null @@ -1,7 +0,0 @@ -#!/bin/bash -cd "$(dirname -- "$(dirname -- "$(readlink -f -- "$0")")")" - -# Remove trailing whitespace for all JS/CSS/SCSS/txt/JSON/SVG static files -find intranet/static -name vendor -prune -o -type f '(' -name '*.js' -o -name '*.css' -o -name '*.scss' -o -name '*.txt' -o -name '*.json' -o -name '*.svg' ')' -exec sed -i 's/\s\+$//' '{}' ';' -# Remove trailing whitespace for all templates -find intranet/templates -type f -exec sed -i 's/\s\+$//' '{}' ';'