mirror of
https://github.com/inventree/InvenTree.git
synced 2026-11-14 12:32:44 +00:00
Oliver
19dfb81bfb
* add zensical workflow * rebuild schema dynamically * load in new module * Use zensical for docs invoke tasks * modern * improved carousel layout * Increased content width * fix for app icons * Ensure schema dir exists * remove unused requirement * update readthedocs process * fix polar.sh link * adjust link checker pattern * Revert some of the original style * remove legacy mkdocs requirements * fix for ready.py * reduce db warnings during schema generation * Adjust padding * fix index issues * fix page title * fix pages with broken or missing headers * split data import API schema * cleanup old carousel * remove djlint link
616 lines
22 KiB
Python
616 lines
22 KiB
Python
"""Main entry point for the documentation build process."""
|
|
|
|
import os
|
|
import subprocess
|
|
import sys
|
|
import textwrap
|
|
from pathlib import Path
|
|
from typing import Literal, Optional
|
|
|
|
import requests
|
|
import yaml
|
|
|
|
# Read in the InvenTree settings file
|
|
here = Path(__file__).parent
|
|
|
|
gen_base = here.joinpath('generated')
|
|
|
|
# Generated data is loaded (and cached) by a separate module, as some static site
|
|
# generators (e.g. zensical) re-execute this file for every page.
|
|
if str(here) not in sys.path:
|
|
sys.path.append(str(here))
|
|
|
|
import docs_data
|
|
|
|
|
|
def get_repo_url(raw=False):
|
|
"""Return the repository URL for the current project."""
|
|
mkdocs_yml = here.joinpath('mkdocs.yml')
|
|
|
|
with open(mkdocs_yml, encoding='utf-8') as f:
|
|
mkdocs_config = yaml.load(f, yaml.BaseLoader)
|
|
repo_name = mkdocs_config['repo_name']
|
|
|
|
if raw:
|
|
return f'https://raw.githubusercontent.com/{repo_name}'
|
|
else:
|
|
return f'https://github.com/{repo_name}'
|
|
|
|
|
|
def check_link(url) -> bool:
|
|
"""Check that a provided URL is valid.
|
|
|
|
We allow a number attempts and a lengthy timeout,
|
|
as we do not want false negatives.
|
|
"""
|
|
CACHE_FILE = gen_base.joinpath('url_cache.txt')
|
|
|
|
# Keep a local cache file of URLs we have already checked
|
|
if CACHE_FILE.exists():
|
|
with open(CACHE_FILE, encoding='utf-8') as f:
|
|
cache = f.read().splitlines()
|
|
|
|
if url in cache:
|
|
return True
|
|
|
|
attempts = 5
|
|
|
|
while attempts > 0:
|
|
response = requests.head(url, timeout=5000)
|
|
|
|
# Ensure GH is not causing issues
|
|
if response.status_code in (200, 429):
|
|
# Update the cache file
|
|
with open(CACHE_FILE, 'a', encoding='utf-8') as f:
|
|
f.write(f'{url}\n')
|
|
|
|
return True
|
|
|
|
attempts -= 1
|
|
|
|
print(f'URL check failed with status code {response.status_code}')
|
|
|
|
return False
|
|
|
|
|
|
def get_build_environment() -> Optional[str]:
|
|
"""Returns the branch we are currently building on, based on the environment variables of the various CI platforms."""
|
|
# Check if we are in ReadTheDocs
|
|
if os.environ.get('READTHEDOCS') == 'True':
|
|
for var in ['READTHEDOCS_GIT_COMMIT_HASH', 'READTHEDOCS_GIT_IDENTIFIER']:
|
|
if val := os.environ.get(var):
|
|
return val
|
|
# We are in GitHub Actions
|
|
elif os.environ.get('GITHUB_ACTIONS') == 'true':
|
|
return os.environ.get('GITHUB_REF')
|
|
|
|
# Default to 'master' branch
|
|
return 'master'
|
|
|
|
|
|
def apply_hook_config(env):
|
|
"""Provide values normally injected by the 'on_config' mkdocs hook.
|
|
|
|
Zensical does not support mkdocs hooks, so 'config.releases',
|
|
'config.assets_dir' etc are never set. Run the hook ourselves and
|
|
inject the results into the template 'config' variable.
|
|
"""
|
|
template_config = env.variables.get('config')
|
|
|
|
if template_config is None:
|
|
return
|
|
|
|
hook_config = docs_data.hook_config(template_config.get('site_url'))
|
|
|
|
for key in ['releases', 'assets_dir', 'readthedocs', 'version_banner']:
|
|
if key in hook_config:
|
|
template_config[key] = hook_config[key]
|
|
|
|
|
|
def define_env(env):
|
|
"""Define custom environment variables for the documentation build process."""
|
|
apply_hook_config(env)
|
|
|
|
config = env.variables.get('config') or env.config
|
|
assets_dir = config.get('assets_dir', None)
|
|
|
|
if assets_dir is None:
|
|
# Construct the assets directory based on the current build environment
|
|
rtd_version = os.environ.get('READTHEDOCS_VERSION')
|
|
rtd_language = os.environ.get('READTHEDOCS_LANGUAGE')
|
|
|
|
if rtd_version and rtd_language:
|
|
assets_dir = f'/{rtd_language}/{rtd_version}/assets'
|
|
else:
|
|
assets_dir = '/assets'
|
|
|
|
@env.macro
|
|
def sourcedir(dirname: str, branch=None):
|
|
"""Return a link to a directory within the source code repository.
|
|
|
|
Arguments:
|
|
dirname: The name of the directory to link to (relative to the top-level directory)
|
|
branch: The branch of the repository to link to (defaults to the current build environment)
|
|
|
|
Returns:
|
|
A fully qualified URL to the source code directory on GitHub
|
|
|
|
Raises:
|
|
FileNotFoundError: If the directory does not exist, or the generated URL is invalid
|
|
"""
|
|
if branch == None:
|
|
branch = get_build_environment()
|
|
|
|
if dirname.startswith('/'):
|
|
dirname = dirname[1:]
|
|
|
|
# This file exists at ./docs/main.py, so any directory we link to must be relative to the top-level directory
|
|
directory = here.parent.joinpath(dirname)
|
|
if not directory.exists() or not directory.is_dir():
|
|
raise FileNotFoundError(f'Source directory {dirname} does not exist.')
|
|
|
|
repo_url = get_repo_url()
|
|
|
|
url = f'{repo_url}/tree/{branch}/{dirname}'
|
|
|
|
# Check that the URL exists before returning it
|
|
if not check_link(url):
|
|
raise FileNotFoundError(f'URL {url} does not exist.')
|
|
|
|
return url
|
|
|
|
@env.macro
|
|
def sourcefile(filename, branch=None, raw=False):
|
|
"""Return a link to a file within the source code repository.
|
|
|
|
Arguments:
|
|
filename: The name of the file to link to (relative to the top-level directory)
|
|
branch: The branch of the repository to link to (defaults to the current build environment)
|
|
raw: If True, return the raw URL to the file (defaults to False)
|
|
|
|
Returns:
|
|
A fully qualified URL to the source code file on GitHub
|
|
|
|
Raises:
|
|
FileNotFoundError: If the file does not exist, or the generated URL is invalid
|
|
"""
|
|
if branch == None:
|
|
branch = get_build_environment()
|
|
|
|
if filename.startswith('/'):
|
|
filename = filename[1:]
|
|
|
|
# This file exists at ./docs/main.py, so any file we link to must be relative to the top-level directory
|
|
file_path = here.parent.joinpath(filename)
|
|
if not file_path.exists():
|
|
raise FileNotFoundError(f'Source file {filename} does not exist.')
|
|
|
|
# Construct repo URL
|
|
repo_url = get_repo_url(raw=False)
|
|
url = f'{repo_url}/blob/{branch}/{filename}'
|
|
|
|
# Check that the URL exists before returning it
|
|
if not check_link(url):
|
|
raise FileNotFoundError(f'URL {url} does not exist.')
|
|
|
|
if raw:
|
|
# If requesting the 'raw' URL, take this into account here...
|
|
repo_url = get_repo_url(raw=True)
|
|
url = f'{repo_url}/{branch}/{filename}'
|
|
|
|
return url
|
|
|
|
@env.macro
|
|
def invoke_commands(command: str = '--list'):
|
|
"""Provides an output of the available commands."""
|
|
tasks = here.parent.joinpath('tasks.py')
|
|
output = gen_base.joinpath('invoke-commands.txt')
|
|
|
|
command = f'invoke -f {tasks} {command} > {output}'
|
|
|
|
assert subprocess.call(command, shell=True) == 0
|
|
|
|
with open(output, encoding='utf-8') as f:
|
|
content = f.read()
|
|
|
|
return content
|
|
|
|
@env.macro
|
|
def listimages(subdir):
|
|
"""Return a listing of all asset files in the provided subdir."""
|
|
directory = here.joinpath('docs', 'assets', 'images', subdir)
|
|
|
|
assets = []
|
|
|
|
allowed = ['.png', '.jpg']
|
|
|
|
for asset in directory.iterdir():
|
|
if any(str(asset).endswith(x) for x in allowed):
|
|
assets.append(str(subdir / asset.relative_to(directory)))
|
|
|
|
return assets
|
|
|
|
@env.macro
|
|
def includefile(filename: str, title: str, fmt: str = ''):
|
|
"""Include a file in the documentation, in a 'collapse' block.
|
|
|
|
Arguments:
|
|
filename: The name of the file to include (relative to the top-level directory)
|
|
title: The title of the collapse block in the documentation
|
|
fmt: The format of the included file (e.g., 'python', 'html', etc.)
|
|
"""
|
|
path = here.parent.joinpath(filename)
|
|
|
|
if not path.exists():
|
|
raise FileNotFoundError(f'Required file {path} does not exist.')
|
|
|
|
with open(path, encoding='utf-8') as f:
|
|
content = f.read()
|
|
|
|
data = f'??? abstract "{title}"\n\n'
|
|
data += f' ```{fmt}\n'
|
|
data += textwrap.indent(content, ' ')
|
|
data += '\n\n'
|
|
data += ' ```\n\n'
|
|
|
|
return data
|
|
|
|
@env.macro
|
|
def templatefile(filename):
|
|
"""Include code for a provided template file."""
|
|
base = Path(filename).name
|
|
fn = Path('src', 'backend', 'InvenTree', 'report', 'templates', filename)
|
|
|
|
return includefile(fn, f'Template: {base}', fmt='html')
|
|
|
|
@env.macro
|
|
def statuscodes(class_name: str):
|
|
"""Render a markdown table of status codes for the given StatusCode class.
|
|
|
|
Arguments:
|
|
class_name: The name of the `StatusCode` subclass to render (e.g. 'BuildStatus')
|
|
|
|
The table is built directly from `docs/generated/inventree_status_codes.json`
|
|
(produced by the `export_status_codes` management command), so it can never
|
|
drift out of sync with the status codes actually defined in the source code.
|
|
"""
|
|
status_class = docs_data.status_codes()[class_name]
|
|
|
|
# Record that this status code class has been rendered somewhere in the docs
|
|
docs_data.observe_status_code(class_name)
|
|
|
|
ret_data = '| Status | Value | Description |\n| --- | --- | --- |\n'
|
|
|
|
for item in status_class['values']:
|
|
description = item['description'] or item['label']
|
|
ret_data += f'| {item["label"]} | {item["key"]} | {description} |\n'
|
|
|
|
return ret_data
|
|
|
|
def observe_setting(key: str, group: str):
|
|
"""Record that a particular setting has been observed.
|
|
|
|
This is used to ensure that all settings are documented in the generated documentation.
|
|
|
|
Arguments:
|
|
key: The name of the setting to observe
|
|
group: The group of the setting (e.g. 'global', 'user')
|
|
"""
|
|
docs_data.observe_setting(key, group)
|
|
|
|
@env.macro
|
|
def rendersetting(
|
|
key: str, setting: dict, short: bool = False, default: Optional[str] = None
|
|
):
|
|
"""Render a provided setting object into a table row.
|
|
|
|
Arguments:
|
|
key: The name of the setting to extract information for.
|
|
setting: The setting object to render.
|
|
short: If True, return a short version of the setting (default: False)
|
|
default: An optional default value to override the setting's default display value.
|
|
"""
|
|
name = setting['name']
|
|
description = setting['description']
|
|
default = default or setting.get('default')
|
|
units = setting.get('units')
|
|
|
|
default = f'`{default}`' if default else ''
|
|
units = f'`{units}`' if units else ''
|
|
|
|
if short:
|
|
return f'<span title="{key}"><strong>{name}</strong></span>'
|
|
|
|
return f'| <div title="{key}"><strong>{name}</strong></div> | {description} | {default} | {units} |'
|
|
|
|
@env.macro
|
|
def globalsetting(key: str, short: bool = False, default: Optional[str] = None):
|
|
"""Extract information on a particular global setting.
|
|
|
|
Arguments:
|
|
key: The name of the global setting to extract information for.
|
|
short: If True, return a short version of the setting (default: False)
|
|
default: An optional default value to override the setting's default display value.
|
|
"""
|
|
setting = docs_data.settings('global')[key]
|
|
|
|
# Settings are only 'observed' if they are displayed in full
|
|
if not short:
|
|
observe_setting(key, 'global')
|
|
|
|
return rendersetting(key, setting, short=short, default=default)
|
|
|
|
@env.macro
|
|
def usersetting(key: str, short: bool = False):
|
|
"""Extract information on a particular user setting.
|
|
|
|
Arguments:
|
|
key: The name of the user setting to extract information for.
|
|
short: If True, return a short version of the setting (default: False)
|
|
"""
|
|
setting = docs_data.settings('user')[key]
|
|
|
|
# Settings are only 'observed' if they are displayed in full
|
|
if not short:
|
|
observe_setting(key, 'user')
|
|
|
|
return rendersetting(key, setting, short=short)
|
|
|
|
@env.macro
|
|
def configtable():
|
|
"""Generate a header for the configuration settings table."""
|
|
return '| Environment Variable | Configuration File | Default | Description |\n| --- | --- | --- | --- |'
|
|
|
|
@env.macro
|
|
def configsetting(key: str, default: Optional[str] = None):
|
|
"""Extract information on a particular configuration setting.
|
|
|
|
Arguments:
|
|
key: The name of the configuration setting to extract information for.
|
|
default: An optional default value to override the setting's default display value.
|
|
"""
|
|
setting = docs_data.settings('config')[key]
|
|
|
|
observe_setting(key, 'config')
|
|
|
|
cfg_key = setting.get('config_key', None)
|
|
cfg_key = f'`{cfg_key}`' if cfg_key else '-'
|
|
|
|
default = default or setting.get('default_value', None)
|
|
|
|
if default is None:
|
|
default = '*Not Specified*'
|
|
|
|
return f'| <span title="{key}" style="white-space: nowrap;"><code>{key}</code></span> | {cfg_key} | {default} |'
|
|
|
|
@env.macro
|
|
def tags_and_filters():
|
|
"""Return a list of all tags and filters."""
|
|
ret_data = ''
|
|
for ref in [['Tags', docs_data.tags()], ['Filters', docs_data.filters()]]:
|
|
ret_data += f'### {ref[0]}\n\n| Namespace | Name | Description |\n| --- | --- | --- |\n'
|
|
for value in ref[1]:
|
|
title = (
|
|
value['title']
|
|
.replace('\n', ' ')
|
|
.replace('<', '<')
|
|
.replace('>', '>')
|
|
)
|
|
ret_data += f'| {value["library"]} | {value["name"]} | {title} |\n'
|
|
ret_data += '\n'
|
|
ret_data += '\n'
|
|
|
|
return ret_data
|
|
|
|
@env.macro
|
|
def roles():
|
|
"""Render a markdown table of the available user permission roles.
|
|
|
|
The table is built directly from `docs/generated/inventree_roles.json`
|
|
(produced by the `export_roles` management command, sourced from
|
|
`users.ruleset.RULESET_CHOICES`), so it can never drift out of sync with
|
|
the roles actually defined in the source code.
|
|
"""
|
|
ret_data = '| Role | Description |\n| --- | --- |\n'
|
|
|
|
for role in docs_data.roles():
|
|
description = role['description'] or role['label']
|
|
ret_data += f'| **{role["label"]}** | {description} |\n'
|
|
|
|
return ret_data
|
|
|
|
@env.macro
|
|
def audited_models():
|
|
"""Render a markdown table of the models which are recorded in the audit log.
|
|
|
|
The table is built directly from `docs/generated/inventree_audited_models.json`
|
|
(produced by the `export_audited_models` management command, sourced from
|
|
the models which implement `InvenTreeAuditMixin`), so it can never drift out
|
|
of sync with the models actually audited in the source code.
|
|
"""
|
|
ret_data = '| Category | Model | Model Type | Parent | Notes |\n'
|
|
ret_data += '| --- | --- | --- | --- | --- |\n'
|
|
|
|
for model in docs_data.audited_models():
|
|
parent = model['parent']
|
|
notes = model['parent_note']
|
|
|
|
if fields := model['include_fields']:
|
|
fields = ', '.join(f'`{field}`' for field in fields)
|
|
notes = f'Only the following fields are recorded: {fields}'
|
|
|
|
ret_data += f'| {model["app"]} | {model["name"]} | `{model["model_type"]}` | {parent} | {notes} |\n'
|
|
|
|
return ret_data
|
|
|
|
@env.macro
|
|
def report_context(type_: Literal['models', 'base'], model: str):
|
|
"""Extract information on a particular report context."""
|
|
context = docs_data.report_context().get(type_).get(model)
|
|
|
|
ret_data = '| Variable | Type | Description |\n| --- | --- | --- |\n'
|
|
for k, v in context['context'].items():
|
|
ret_data += f'| {k} | `{v["type"]}` | {v["description"]} |\n'
|
|
|
|
return ret_data
|
|
|
|
def render_attribute_table(attributes: dict, title: str) -> str:
|
|
"""Render a table of field/property information, in a collapsible (collapsed by default) block.
|
|
|
|
Returns an empty string (including no block) if there is nothing to display.
|
|
"""
|
|
if not attributes:
|
|
return ''
|
|
|
|
table = '| Variable | Type | Description |\n| --- | --- | --- |\n'
|
|
|
|
for k, v in sorted(attributes.items()):
|
|
description = ' '.join(v['description'].split())
|
|
table += f'| {k} | `{v["type"]}` | {description} |\n'
|
|
|
|
ret_data = f'??? note "{title}"\n\n'
|
|
ret_data += textwrap.indent(table, ' ')
|
|
|
|
# Trailing blank line, so consecutive macro calls (e.g. fields followed by
|
|
# properties) don't run together when the template places them on adjacent lines
|
|
return ret_data + '\n'
|
|
|
|
@env.macro
|
|
def reportable_model_context():
|
|
"""Render the full 'reportable model types' section.
|
|
|
|
One heading plus fields/properties tables per model which templates can be
|
|
rendered against (e.g. `Part`, `SalesOrder`, `StockItem`). The list of models
|
|
comes directly from what `export_report_context` discovered via the
|
|
`InvenTreeReportMixin`, so there is no manually-maintained per-model heading
|
|
list to keep in sync here.
|
|
"""
|
|
models = docs_data.report_context().get('models', {})
|
|
|
|
ret_data = ''
|
|
|
|
for info in sorted(models.values(), key=lambda item: item['name']):
|
|
ret_data += f'### {info["name"]}\n\n'
|
|
ret_data += render_attribute_table(info.get('fields', {}), 'Fields')
|
|
ret_data += render_attribute_table(info.get('properties', {}), 'Properties')
|
|
|
|
return ret_data
|
|
|
|
@env.macro
|
|
def related_model_context():
|
|
"""Render the full 'related model types' section.
|
|
|
|
A "related" model is one which is not itself reportable, but which is
|
|
referenced by a field or `@report_attribute` property on a reportable model
|
|
(e.g. `PartCategory` via `Part.category`, `SupplierPart` via `Part.default_supplier`).
|
|
|
|
These are discovered automatically (one hop out from the reportable models) by
|
|
the `export_report_context` management command, so there is no manually-maintained
|
|
list of related models to keep in sync here.
|
|
"""
|
|
related = docs_data.report_context().get('related_models', {})
|
|
|
|
ret_data = ''
|
|
|
|
for info in sorted(related.values(), key=lambda item: item['name']):
|
|
ret_data += f'### {info["name"]}\n\n'
|
|
ret_data += render_attribute_table(info.get('fields', {}), 'Fields')
|
|
ret_data += render_attribute_table(info.get('properties', {}), 'Properties')
|
|
|
|
return ret_data
|
|
|
|
@env.macro
|
|
def icon(
|
|
source: str,
|
|
size: str = '20px',
|
|
color: Optional[str] = None,
|
|
title: Optional[str] = None,
|
|
):
|
|
"""Return a tabler icon for a given source.
|
|
|
|
Arguments:
|
|
source: The name of the icon to display (e.g. 'check', 'cross', etc.)
|
|
size: The size of the icon (default: 20px)
|
|
color: The color of the icon (default: None)
|
|
title: The title of the icon (default: None)
|
|
|
|
Requires CSS to be loaded from:
|
|
https://cdn.jsdelivr.net/npm/@tabler/icons-webfont@3.31.0/dist/tabler-icons.min.css
|
|
"""
|
|
c = f' color: {color};' if color else ''
|
|
t = f' <i>{title}</i>' if title else ''
|
|
|
|
return f"<i class='ti ti-{source}' style='font-size: {size};{c}'></i>{t}"
|
|
|
|
@env.macro
|
|
def image(
|
|
source: str,
|
|
title: Optional[str] = '',
|
|
iid: Optional[str] = '',
|
|
alt: Optional[str] = '',
|
|
base: Optional[str] = '',
|
|
maxwidth: Optional[str] = '',
|
|
maxheight: Optional[str] = '',
|
|
):
|
|
"""Render an image within the documentation.
|
|
|
|
Arguments:
|
|
title: The title of the image (default: '')
|
|
source: The name of the image to display (e.g. 'check', 'cross', etc.)
|
|
iid: The ID of the image (default: '')
|
|
alt: The alt text for the image (default: '')
|
|
base: The base directory for the image (default: './assets/images/')
|
|
maxwidth: The maximum width of the image (default: '')
|
|
maxheight: The maximum height of the image (default: '')
|
|
|
|
- This will render an image which can be clicked on to expand to full size.
|
|
- It will also validate that the image exists in the specified directory.
|
|
|
|
The image must be located in the './docs/assets/images/' directory
|
|
"""
|
|
# Allow external images too - without validation
|
|
if source.startswith('http'):
|
|
img = source
|
|
else:
|
|
basedir = os.path.dirname(__file__)
|
|
basedir = os.path.join(basedir, 'docs', 'assets', 'images')
|
|
|
|
if base:
|
|
basedir = os.path.abspath(os.path.join(basedir, base))
|
|
filename = os.path.join(basedir, source)
|
|
|
|
if not os.path.exists(filename):
|
|
raise FileNotFoundError(f'Image {filename} does not exist.')
|
|
|
|
# Now, create a proper URL to the image
|
|
img = os.path.join(assets_dir, 'images', base, source)
|
|
|
|
if not title:
|
|
title = os.path.splitext(source)[0]
|
|
|
|
if not iid:
|
|
iid = title.replace(' ', '_').replace('-', '_')
|
|
|
|
if not alt:
|
|
alt = iid
|
|
|
|
styles = []
|
|
|
|
if maxwidth:
|
|
styles.append(f'max-width: {maxwidth};')
|
|
if maxheight:
|
|
styles.append(f'max-height: {maxheight};')
|
|
|
|
style = f"style='{' '.join(styles)}' " if styles else ''
|
|
|
|
return textwrap.dedent(f"""
|
|
<figure class='image image-inventree'>
|
|
<a href='#{iid}'>
|
|
<img class='img-inline' src='{img}' alt='{alt}' title='{title}' {style}/>
|
|
</a>
|
|
<a href='#_' class='overlay' id='{iid}'>
|
|
<img src='{img}' alt='{alt}' />
|
|
</a>
|
|
</figure>
|
|
""")
|