From 13d866bd0d87451d1f7879ad8e3fb3c5b7e65002 Mon Sep 17 00:00:00 2001 From: Ariel Rin Date: Fri, 27 Oct 2023 16:37:09 +1000 Subject: [PATCH] RST to MyST, pyproject doc dependencies, add sphinx tabs --- .readthedocs.yml | 11 +++-- README.md | 2 +- docs/conf.py | 104 +++++++++++++----------------------------- docs/requirements.txt | 20 -------- pyproject.toml | 10 +++- 5 files changed, 49 insertions(+), 98 deletions(-) delete mode 100644 docs/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml index 936dbfe8..6837aabd 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -7,11 +7,11 @@ version: 2 # Set the version of Python and other tools you might need build: - os: ubuntu-20.04 + os: ubuntu-22.04 apt_packages: - redis tools: - python: "3.8" + python: "3.11" # Build documentation in the docs/ directory with Sphinx sphinx: @@ -20,7 +20,10 @@ sphinx: # Optionally build your docs in additional formats such as PDF and ePub formats: all -# Optionally set the version of Python and requirements required to build your docs +# Python requirements required to build your docs python: install: - - requirements: docs/requirements.txt + - method: pip + path: . + extra_requirements: + - docs diff --git a/README.md b/README.md index 7c6bc43e..5e9f5e94 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ An auth system for EVE Online to help in-game organizations manage online servic - [Documentation](http://allianceauth.rtfd.io) - [Support](#support) - [Release Notes](https://gitlab.com/allianceauth/allianceauth/-/releases) -- [Developer Team](#developer-team) +- [Developer Team](#development-team) - [Contributing](#contributing) ## Overview diff --git a/docs/conf.py b/docs/conf.py index 87502ae6..71a047e9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,15 +1,10 @@ +# Configuration file for the Sphinx documentation builder. # -# Alliance Auth documentation build configuration file, created by -# sphinx-quickstart on Tue Jan 3 12:56:59 2017. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- 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 @@ -18,23 +13,23 @@ import os import sys import django +import sphinx_rtd_theme # noqa + sys.path.insert(0, os.path.abspath('..')) os.environ['DJANGO_SETTINGS_MODULE'] = 'tests.settings_all' django.setup() +# -- Project information ----------------------------------------------------- + +project = 'Alliance Auth' +copyright = '2018-2023, Alliance Auth' +author = 'Alliance Auth Team' + +# -- General configuration --------------------------------------------------- + # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org on_rtd = os.environ.get('READTHEDOCS', None) == 'True' -# Support for recommonmark module -import recommonmark -from recommonmark.transform import AutoStructify - -# -- 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. @@ -42,11 +37,18 @@ from recommonmark.transform import AutoStructify extensions = [ 'sphinx_rtd_theme', 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon', - 'recommonmark', - 'sphinxcontrib_django2', 'sphinx.ext.viewcode', - 'sphinx_copybutton' + 'myst_parser', + 'sphinxcontrib_django2', + 'sphinx_copybutton', + 'sphinx_tabs.tabs' +] + +myst_enable_extensions = [ + "colon_fence", + "tasklist", ] # Add any paths that contain templates here, relative to this directory. @@ -59,41 +61,16 @@ templates_path = ['_templates'] source_suffix = ['.md', '.rst'] # The master toctree document. -master_doc = 'index' - -# General information about the project. -project = 'Alliance Auth' -copyright = '2018-2022, Alliance Auth' -author = 'Alliance Auth Team' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '3.0' -# The full version, including alpha/beta/rc tags. -# release = u'1.14.0' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = 'en' +root_doc = 'index' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False - # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for @@ -101,15 +78,6 @@ todo_include_todos = False # html_theme = 'sphinx_rtd_theme' -# 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_depth': 4, -} - # 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". @@ -147,7 +115,7 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'AllianceAuth.tex', 'Alliance Auth Documentation', 'R4stl1n', 'manual'), + (root_doc, 'AllianceAuth.tex', 'Alliance Auth Documentation', 'Alliance Auth Team', 'manual'), ] @@ -156,7 +124,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'allianceauth', 'Alliance Auth Documentation', + (root_doc, 'allianceauth', 'Alliance Auth Documentation', [author], 1) ] @@ -169,15 +137,7 @@ add_module_names = False # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'AllianceAuth', 'Alliance Auth Documentation', - author, 'AllianceAuth', 'An auth system for EVE Online to help in-game organizations manage online service access.', - 'Miscellaneous'), +texinfo_documents = [( + root_doc, 'AllianceAuth', 'Alliance Auth Documentation', author, 'AllianceAuth', + 'An auth system for EVE Online to help in-game organizations manage online service access.', 'Miscellaneous'), ] - - -def setup(app): - app.add_config_value('recommonmark_config', { - 'auto_toc_tree_section': 'Contents', - }, True) - app.add_transform(AutoStructify) diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index fc8d395c..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,20 +0,0 @@ -# Docs Specific Packages -sphinx>=4.4.0,<5.0.0 -sphinx_rtd_theme>=1.0.0,<2.0.0 -recommonmark==0.7.1 -Jinja2<3.1 -docutils==0.16 -sphinxcontrib-django2 -sphinx-copybutton - -# Autodoc dependencies -celery>=5.2.0,<6.0.0 -celery_once>=3.0.1 -django>=4.0.6,<4.1.0 -django-bootstrap-form -django-celery-beat>=2.3.0 -django-esi>=4.0.1 -django-redis>=5.2.0,<6.0.0 -django-sortedm2m -passlib -redis>=4.0.0,<5.0.0 diff --git a/pyproject.toml b/pyproject.toml index 18318565..efa516a5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -60,7 +60,15 @@ dependencies = [ test = [ "coverage>=4.3.1", "django-webtest", - "requests-mock>=1.2.0", + "requests-mock>=1.2.0" +] +docs = [ + "sphinx", + "sphinx_rtd_theme>=1.0.0,<2.0.0", + "myst-parser", + "sphinxcontrib-django", + "sphinx-copybutton", + "sphinx-tabs", ] [project.scripts]