forked from extern/httpie-cli
08751d3672
* Add install/update instructions database * Update the database * Revert README changes They will be overwritten later. * Revert * Tweak * Tweaks * Upgrade database * Complete commands Still not sure about Spack upgrades. * Sort * Doc generation script draft * Remove OS names from tool names * Fix Linuxbrew name * `wheel` already installs `setuptools` * Gen docs * Update * Tweak * Add a GitHub workflow to check for outdated installation instructions * Fix return value * Test * Delete test * Rename the script * Add `make doc-install-inst` * Add missing dev requirement * The first tool is the primary we want to display Then they are simply sorted by `tool.title`. * Sort OSes by name * Refactoring, jinja template, etc. * Add tool title uniqueness `assert`, fix platform list extra `\n` * Rebuild docs * Update generate.py * Update README.md * Update methods.yml * Update distros derived, more assertions * Tweaks * Add workflow to auto-update the docs * Do not hide the command * Tweaks Co-authored-by: Jakub Roztocil <jakub@roztocil.co>
86 lines
2.3 KiB
Python
86 lines
2.3 KiB
Python
import re
|
|
import sys
|
|
from pathlib import Path
|
|
from typing import Dict
|
|
|
|
import yaml
|
|
from jinja2 import Template
|
|
|
|
Database = Dict[str, dict]
|
|
|
|
# Files
|
|
HERE = Path(__file__).parent
|
|
DB_FILE = HERE / 'methods.yml'
|
|
DOC_FILE = HERE.parent / 'README.md'
|
|
TPL_FILE = HERE / 'installation.jinja2'
|
|
|
|
# Database keys
|
|
KEY_DOC_STRUCTURE = 'docs-structure'
|
|
KEY_TOOLS = 'tools'
|
|
|
|
# Markers in-between content will be put.
|
|
MARKER_START = '<div data-installation-instructions>'
|
|
MARKER_END = '</div>'
|
|
|
|
|
|
def generate_documentation() -> str:
|
|
database = load_database()
|
|
structure = build_docs_structure(database)
|
|
template = Template(source=TPL_FILE.read_text(encoding='utf-8'))
|
|
output = template.render(structure=structure)
|
|
output = clean_template_output(output)
|
|
return output
|
|
|
|
|
|
def save_doc_file(content: str) -> None:
|
|
current_doc = load_doc_file()
|
|
marker_start = current_doc.find(MARKER_START) + len(MARKER_START)
|
|
assert marker_start > 0, 'cannot find the start marker'
|
|
marker_end = current_doc.find(MARKER_END, marker_start)
|
|
assert marker_start < marker_end, f'{marker_end=} < {marker_start=}'
|
|
updated_doc = (
|
|
current_doc[:marker_start]
|
|
+ '\n\n'
|
|
+ content
|
|
+ '\n\n'
|
|
+ current_doc[marker_end:]
|
|
)
|
|
if current_doc != updated_doc:
|
|
DOC_FILE.write_text(updated_doc, encoding='utf-8')
|
|
|
|
|
|
def build_docs_structure(database: Database):
|
|
tools = database[KEY_TOOLS]
|
|
assert len(tools) == len({tool['title'] for tool in tools.values()}), 'tool titles need to be unique'
|
|
tree = database[KEY_DOC_STRUCTURE]
|
|
structure = []
|
|
for platform, tools_ids in tree.items():
|
|
assert platform.isalnum(), f'{platform=} must be alpha-numeric for generated links to work'
|
|
platform_tools = [tools[tool_id] for tool_id in tools_ids]
|
|
structure.append((platform, platform_tools))
|
|
return structure
|
|
|
|
|
|
def clean_template_output(output):
|
|
output = '\n'.join(line.strip() for line in output.strip().splitlines())
|
|
output = re.sub('\n{3,}', '\n\n', output)
|
|
return output
|
|
|
|
|
|
def load_database() -> Database:
|
|
return yaml.safe_load(DB_FILE.read_text(encoding='utf-8'))
|
|
|
|
|
|
def load_doc_file() -> str:
|
|
return DOC_FILE.read_text(encoding='utf-8')
|
|
|
|
|
|
def main() -> int:
|
|
content = generate_documentation()
|
|
save_doc_file(content)
|
|
return 0
|
|
|
|
|
|
if __name__ == '__main__':
|
|
sys.exit(main())
|