inventree/InvenTree
2
0
Fork 0
mirror of https://github.com/inventree/InvenTree.git synced 2025-06-14 11:05:41 +00:00
Code Activity

refactor(docs): simplify docs files / pipelines (#9633)

Browse Source 
* refactor(doc): only use one command

* restructure

* move all generated helpers to a dedicated directory

* move to pathlib

* and more pathlib

* add empty generated folder
This commit is contained in:
Matthias Mair
2025-05-06 13:20:11 +02:00
committed by GitHub
parent 6d0a08d1f5
commit 0ff86103d9
8 changed files with 70 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/.gitignore vendored
View File

@ -13,20 +13,5 @@ site/
# Generated API schema files
docs/api/schema/*.yml
# Temporary cache files
url_cache.txt
invoke-commands.txt
# Temp files
releases.json
versions.json
inventree_filters.yml
inventree_settings.json
inventree_tags.yml
.vscode/
inventree_filters.yml
inventree_report_context.json
inventree_settings.json
inventree_tags.yml
generated/

15
docs/docs/hooks.py
View File

@ -5,9 +5,12 @@ import os
import re
from datetime import datetime
from distutils.version import StrictVersion
from pathlib import Path
import requests
here = Path(__file__).parent
def fetch_rtd_versions():
"""Get a list of RTD docs versions to build the version selector."""
@ -77,7 +80,7 @@ def fetch_rtd_versions():
'aliases': [],
})
output_filename = os.path.join(os.path.dirname(__file__), 'versions.json')
output_filename = here.joinpath('versions.json')
print('Discovered the following versions:')
print(versions)
@ -92,11 +95,11 @@ def get_release_data():
- First look to see if 'releases.json' file exists
- If data does not exist in this file, request via the github API
"""
json_file = os.path.join(os.path.dirname(__file__), 'releases.json')
json_file = here.parent.joinpath('generated', 'releases.json')
releases = []
if os.path.exists(json_file):
if json_file.exists():
# Release information has been cached to file
print("Loading release information from 'releases.json'")
@ -165,7 +168,7 @@ def on_config(config, *args, **kwargs):
# Note: version selection is handled by RTD internally
# Check for 'versions.json' file
# If it does not exist, we need to fetch it from the RTD API
# if os.path.exists(os.path.join(os.path.dirname(__file__), 'versions.json')):
# if here.joinpath('versions.json').exists():
# print("Found 'versions.json' file")
# else:
# fetch_rtd_versions()
@ -230,9 +233,9 @@ def on_config(config, *args, **kwargs):
continue
# Check if there is a local file with release information
local_path = os.path.join(os.path.dirname(__file__), 'releases', f'{tag}.md')
local_path = here.joinpath('releases', f'{tag}.md')
if os.path.exists(local_path):
if local_path.exists():
item['local_path'] = local_path
# Extract the date

1
docs/generated/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
*

66
docs/main.py
View File

@ -4,6 +4,7 @@ import json
import os
import subprocess
import textwrap
from pathlib import Path
from typing import Literal, Optional
import requests
@ -37,29 +38,29 @@ global FILTERS
global REPORT_CONTEXT
# Read in the InvenTree settings file
here = os.path.dirname(__file__)
settings_file = os.path.join(here, 'inventree_settings.json')
here = Path(__file__).parent
gen_base = here.joinpath('generated')
with open(settings_file, encoding='utf-8') as sf:
with open(gen_base.joinpath('inventree_settings.json'), encoding='utf-8') as sf:
settings = json.load(sf)
GLOBAL_SETTINGS = settings['global']
USER_SETTINGS = settings['user']
# Tags
with open(os.path.join(here, 'inventree_tags.yml'), encoding='utf-8') as f:
with open(gen_base.joinpath('inventree_tags.yml'), encoding='utf-8') as f:
TAGS = yaml.load(f, yaml.BaseLoader)
# Filters
with open(os.path.join(here, 'inventree_filters.yml'), encoding='utf-8') as f:
with open(gen_base.joinpath('inventree_filters.yml'), encoding='utf-8') as f:
FILTERS = yaml.load(f, yaml.BaseLoader)
# Report context
with open(os.path.join(here, 'inventree_report_context.json'), encoding='utf-8') as f:
with open(gen_base.joinpath('inventree_report_context.json'), encoding='utf-8') as f:
REPORT_CONTEXT = json.load(f)
def get_repo_url(raw=False):
"""Return the repository URL for the current project."""
mkdocs_yml = os.path.join(os.path.dirname(__file__), 'mkdocs.yml')
mkdocs_yml = here.joinpath('mkdocs.yml')
with open(mkdocs_yml, encoding='utf-8') as f:
mkdocs_config = yaml.safe_load(f)
@ -77,10 +78,10 @@ def check_link(url) -> bool:
We allow a number attempts and a lengthy timeout,
as we do not want false negatives.
"""
CACHE_FILE = os.path.join(os.path.dirname(__file__), 'url_cache.txt')
CACHE_FILE = gen_base.joinpath('url_cache.txt')
# Keep a local cache file of URLs we have already checked
if os.path.exists(CACHE_FILE):
if CACHE_FILE.exists():
with open(CACHE_FILE, encoding='utf-8') as f:
cache = f.read().splitlines()
@ -93,6 +94,7 @@ def check_link(url) -> bool:
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
@ -147,13 +149,8 @@ def define_env(env):
dirname = dirname[1:]
# This file exists at ./docs/main.py, so any directory we link to must be relative to the top-level directory
here = os.path.dirname(__file__)
root = os.path.abspath(os.path.join(here, '..'))
directory = os.path.join(root, dirname)
directory = os.path.abspath(directory)
if not os.path.exists(directory) or not os.path.isdir(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()
@ -188,12 +185,8 @@ def define_env(env):
filename = filename[1:]
# This file exists at ./docs/main.py, so any file we link to must be relative to the top-level directory
here = os.path.dirname(__file__)
root = os.path.abspath(os.path.join(here, '..'))
file_path = os.path.join(root, filename)
if not os.path.exists(file_path):
file_path = here.parent.joinpath(filename)
if not file_path.exists():
raise FileNotFoundError(f'Source file {filename} does not exist.')
# Construct repo URL
@ -214,11 +207,8 @@ def define_env(env):
@env.macro
def invoke_commands():
"""Provides an output of the available commands."""
here = os.path.dirname(__file__)
base = os.path.join(here, '..')
base = os.path.abspath(base)
tasks = os.path.join(base, 'tasks.py')
output = os.path.join(here, 'invoke-commands.txt')
tasks = here.parent.joinpath('tasks.py')
output = gen_base.joinpath('invoke-commands.txt')
command = f'invoke -f {tasks} --list > {output}'
@ -232,17 +222,15 @@ def define_env(env):
@env.macro
def listimages(subdir):
"""Return a listing of all asset files in the provided subdir."""
here = os.path.dirname(__file__)
directory = os.path.join(here, 'docs', 'assets', 'images', subdir)
directory = here.joinpath('docs', 'assets', 'images', subdir)
assets = []
allowed = ['.png', '.jpg']
for asset in os.listdir(directory):
if any(asset.endswith(x) for x in allowed):
assets.append(os.path.join(subdir, asset))
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
@ -255,11 +243,9 @@ def define_env(env):
title: The title of the collapse block in the documentation
fmt: The format of the included file (e.g., 'python', 'html', etc.)
"""
here = os.path.dirname(__file__)
path = os.path.join(here, '..', filename)
path = os.path.abspath(path)
path = here.parent.joinpath(filename)
if not os.path.exists(path):
if not path.exists():
raise FileNotFoundError(f'Required file {path} does not exist.')
with open(path, encoding='utf-8') as f:
@ -276,10 +262,8 @@ def define_env(env):
@env.macro
def templatefile(filename):
"""Include code for a provided template file."""
base = os.path.basename(filename)
fn = os.path.join(
'src', 'backend', 'InvenTree', 'report', 'templates', filename
)
base = Path(filename).name
fn = Path('src', 'backend', 'InvenTree', 'report', 'templates', filename)
return includefile(fn, f'Template: {base}', fmt='html')