docs: replace scripts with makefile
Part-of: <https://dev.funkwhale.audio/funkwhale/funkwhale/-/merge_requests/2348>
This commit is contained in:
jo
Marge
parent
c5dd88a2e2
commit
fe47420ba1
14 changed files with 538 additions and 3473 deletions
242
docs/conf.py
Executable file → Normal file
242
docs/conf.py
Executable file → Normal file
|
|
@ -1,58 +1,70 @@
|
|||
#!/usr/bin/env python3
|
||||
#
|
||||
# funkwhale documentation build configuration file, created by
|
||||
# sphinx-quickstart on Sun Jun 25 18:49:23 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.
|
||||
|
||||
import datetime
|
||||
|
||||
# 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.
|
||||
#
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
import os
|
||||
import sys
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, os.path.abspath("../api"))
|
||||
sys.path.insert(0, os.path.abspath("../api/config"))
|
||||
from sphinx.application import Sphinx
|
||||
from sphinx.util import logging
|
||||
|
||||
import funkwhale_api
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
import funkwhale_api # NOQA
|
||||
|
||||
FUNKWHALE_CONFIG = {
|
||||
"FUNKWHALE_URL": "mypod.funkwhale",
|
||||
"FUNKWHAL_PROTOCOL": "https",
|
||||
"DATABASE_URL": "postgres://localhost:5432/db",
|
||||
"FUNKWHALE_URL": "https://pod.funkwhale",
|
||||
"DATABASE_URL": "postgres://localhost:5432/funkwhale",
|
||||
"AWS_ACCESS_KEY_ID": "my_access_key",
|
||||
"AWS_SECRET_ACCESS_KEY": "my_secret_key",
|
||||
"AWS_STORAGE_BUCKET_NAME": "my_bucket",
|
||||
}
|
||||
for key, value in FUNKWHALE_CONFIG.items():
|
||||
os.environ[key] = value
|
||||
os.environ.update(**FUNKWHALE_CONFIG)
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#
|
||||
# needs_sphinx = '1.0'
|
||||
# General information about the project.
|
||||
year = datetime.now().year
|
||||
project = "funkwhale"
|
||||
copyright = f"{year}, The Funkwhale Collective"
|
||||
author = "The Funkwhale Collective"
|
||||
version = funkwhale_api.__version__
|
||||
release = version
|
||||
|
||||
# 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.graphviz",
|
||||
"sphinx.ext.autodoc",
|
||||
"myst_parser",
|
||||
"sphinx_design",
|
||||
"sphinxcontrib.mermaid",
|
||||
"sphinx_copybutton",
|
||||
"sphinx_design",
|
||||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.graphviz",
|
||||
"sphinxcontrib.mermaid",
|
||||
"myst_parser",
|
||||
]
|
||||
|
||||
source_suffix = ".md"
|
||||
include_patterns = [
|
||||
"_static/**",
|
||||
"_templates/**",
|
||||
"*_documentation/**",
|
||||
"*.md",
|
||||
"*.rst",
|
||||
"logo.svg",
|
||||
]
|
||||
exclude_patterns = [
|
||||
"_build",
|
||||
"_scripts",
|
||||
".venv",
|
||||
".DS_Store",
|
||||
"Thumbs.db",
|
||||
"*.py",
|
||||
"*.sh",
|
||||
]
|
||||
|
||||
root_doc = "index"
|
||||
|
||||
# autodoc
|
||||
autodoc_mock_imports = [
|
||||
"celery",
|
||||
"django_auth_ldap",
|
||||
|
|
@ -61,20 +73,13 @@ autodoc_mock_imports = [
|
|||
"rest_framework",
|
||||
"drf_spectacular",
|
||||
]
|
||||
|
||||
# sphinx
|
||||
pygments_style = "sphinx"
|
||||
add_module_names = False
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ["_templates"]
|
||||
todo_include_todos = False
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
#
|
||||
# source_suffix = ['.rst', '.md']
|
||||
source_suffix = ".md"
|
||||
|
||||
# The root toctree document.
|
||||
root_doc = "index"
|
||||
|
||||
# Enable colon fences
|
||||
# myst
|
||||
myst_enable_extensions = [
|
||||
"colon_fence",
|
||||
"attrs_block",
|
||||
|
|
@ -82,54 +87,21 @@ myst_enable_extensions = [
|
|||
"fieldlist",
|
||||
"deflist",
|
||||
]
|
||||
|
||||
# Autogenerate anchors
|
||||
|
||||
myst_heading_anchors = 3
|
||||
|
||||
# General information about the project.
|
||||
year = datetime.datetime.now().year
|
||||
project = "funkwhale"
|
||||
copyright = f"{year}, The Funkwhale Collective"
|
||||
author = "The Funkwhale Collective"
|
||||
|
||||
# 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.
|
||||
# Read version from the API
|
||||
version = funkwhale_api.__version__
|
||||
release = version
|
||||
|
||||
# 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.
|
||||
# internationalization
|
||||
locale_dirs = ["locales/"]
|
||||
gettext_compact = False
|
||||
language = "en"
|
||||
|
||||
# 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", ".venv"]
|
||||
# copybutton
|
||||
copybutton_exclude = ".linenos, .gp"
|
||||
|
||||
# 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
|
||||
# a list of builtin themes.
|
||||
#
|
||||
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 = {}
|
||||
html_context = {
|
||||
"display_gitlab": True,
|
||||
"gitlab_host": "dev.funkwhale.audio",
|
||||
|
|
@ -141,61 +113,37 @@ html_context = {
|
|||
}
|
||||
html_logo = "logo.svg"
|
||||
html_favicon = "../front/public/favicon.ico"
|
||||
|
||||
# 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"]
|
||||
html_css_files = [
|
||||
"css/translation-hint.css",
|
||||
]
|
||||
html_js_files = [
|
||||
"js/translation-hint.js",
|
||||
]
|
||||
html_css_files = ["css/translation-hint.css"]
|
||||
html_js_files = ["js/translation-hint.js"]
|
||||
|
||||
# -- Options for HTMLHelp output ------------------------------------------
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = "funkwhaledoc"
|
||||
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#
|
||||
# 'papersize': 'letterpaper',
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#
|
||||
# 'pointsize': '10pt',
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# 'preamble': '',
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# 'figure_align': 'htbp',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(
|
||||
root_doc,
|
||||
"funkwhale.tex",
|
||||
"funkwhale Documentation",
|
||||
"Funkwhale Documentation",
|
||||
"The Funkwhale Collective",
|
||||
"manual",
|
||||
)
|
||||
]
|
||||
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [(root_doc, "funkwhale", "funkwhale Documentation", [author], 1)]
|
||||
|
||||
man_pages = [
|
||||
(
|
||||
root_doc,
|
||||
"funkwhale",
|
||||
"Funkwhale Documentation",
|
||||
[author],
|
||||
1,
|
||||
)
|
||||
]
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
|
|
@ -206,7 +154,7 @@ texinfo_documents = [
|
|||
(
|
||||
root_doc,
|
||||
"funkwhale",
|
||||
"funkwhale Documentation",
|
||||
"Funkwhale Documentation",
|
||||
author,
|
||||
"funkwhale",
|
||||
"One line description of project.",
|
||||
|
|
@ -214,49 +162,35 @@ texinfo_documents = [
|
|||
)
|
||||
]
|
||||
|
||||
# -- Build legacy redirect files -------------------------------------------
|
||||
# -- Setup legacy redirects -----------------------------------------------
|
||||
|
||||
# Define list of redirect files to be build in the Sphinx build process
|
||||
|
||||
redirect_list = []
|
||||
with open("redirects.txt") as fp:
|
||||
data_list = [tuple(line.strip().split(",")) for line in fp]
|
||||
|
||||
# Generate redirect template
|
||||
|
||||
redirect_template = """\
|
||||
REDIRECT_TEMPLATE = """\
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="refresh" content="1; url={new}" />
|
||||
<meta http-equiv="refresh" content="1; url={url}" />
|
||||
<script>
|
||||
window.location.href = "{new}"
|
||||
window.location.href = "{url}"
|
||||
</script>
|
||||
</head>
|
||||
</html>
|
||||
"""
|
||||
|
||||
# Tell Sphinx to copy the files
|
||||
redirects_file = Path("redirects.txt")
|
||||
redirects = [
|
||||
tuple(line.strip().split(", "))
|
||||
for line in redirects_file.read_text(encoding="utf-8").splitlines()
|
||||
]
|
||||
|
||||
|
||||
def copy_legacy_redirects(app, docname):
|
||||
def copy_legacy_redirects(app: Sphinx, docname):
|
||||
if app.builder.name == "html":
|
||||
for html_src_path, new in data_list:
|
||||
page = redirect_template.format(new=new)
|
||||
target_path = app.outdir + "/" + html_src_path
|
||||
if not os.path.exists(os.path.dirname(target_path)):
|
||||
os.makedirs(os.path.dirname(target_path))
|
||||
with open(target_path, "w") as f:
|
||||
f.write(page)
|
||||
for src_path, dest_url in redirects:
|
||||
content = REDIRECT_TEMPLATE.format(url=dest_url)
|
||||
|
||||
redirect_path = Path(app.outdir) / src_path
|
||||
redirect_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
redirect_path.write_text(content, encoding="utf-8")
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.connect("build-finished", copy_legacy_redirects)
|
||||
|
||||
|
||||
# Internationalization settings
|
||||
locale_dirs = ["locales/"]
|
||||
gettext_compact = False
|
||||
|
||||
# Don't copy prompts with copybutton
|
||||
|
||||
copybutton_exclude = ".linenos, .gp"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue