mirror of
https://github.com/ublue-os/bazzite.git
synced 2024-12-29 12:22:20 +00:00
0e18978fe1
* feat: add mdbook docs * chore: add several articles to docs * docs: add documentation at surface level Using Discourse urls as fallback for missing content for now docs: add missing image files * docs: Add missing chapter emojis docs: Add missing warning in Advanced docs in summary docs: add missing waydroid guide docs: rename files to avoid spaces docs: fix badly set docs build params docs: remove unnecesary placeholders * docs: Realocate 'Gaming' section under 'General' * docs: Add 'Introduction' section This section contains a table of contents of the documentation * docs: Add unstable documentation warning * docs: Add missing github url docs: add missing symlink to resources * docs: Add discourse scrapper utility * docs: minor discourse scrapper docs changes * docs: Add youtube embeding preprocessor * minor reformat for youtube-embed * docs: Add mdbook preprocessor template * docs: add format-author preprocessor * docs: add git lib to mdbook toolset * docs: Always fetch the highest quality image by fetch_discourse_md * docs: fix youtube-embed ignoring new line requirement * docs: Add documentation transcription guide * docs: Missing url in transcription guide * docs: Remove YAML header from doc guide * docs: Minor tweaks to transcription guide * docs: Add utilities preprocessor module docs: Move debug preprocessor util to utils * docs: tweak debug function * docs: Add 'replace-urls' preprocessor * chore: Move mappings parameter in replace-urls preprocessor * docs: add ignore field to replace-urls * docs: add Mdbook python types * docs: Add ignore field to replace-urls Now we can exclude files from being processed with blob patterns * chore(ci): add deploy_docs * chore(ci): Add dynamic edit url template to deploy_docs * chore(ci): Add html.site-url to deploy_docs * chore(readme): Use relative paths for repo_content * chore(ci): Add README to included paths for deploy_docs * chore(ci): Disable deploy_docs * chore(ci): Use main in deploy_docs.on.push.branches * docs: Rephrase unstable docs warning * chore(ci): Exclude docs from triggering build workflow * chore(ci): Enable deploy_docs * fix(docs): Remove unnecessary imports in preprocessors * docs: Move unstable docs warning to index.hbs * docs: Add page metadata inclusion with fetch_discourse_md.py * docs: Move fetch_discourse_md.py to docs/utils * docs: Add 'fetched_at' metadata field in fetch_discourse_md.py * docs: Update fetch_discourse_md.py to format metadata in json * Revert "chore(readme): Use relative paths for repo_content" This reverts commit6a781c6596. * docs: Replace include with an url to repo README * ci(docs): Add multilanguage doc build support * docs: add Justfile utility * docs: update Justfile utility * ci(docs): Add stricter workflow trigger to deploy_docs * docs: add 'preview_translation' to Justfile * docs: add documentation translation guide * ci(docs): Add mdbook cache * ci(docs): Add i18n-report * ci(docs): tweak deploy_docs workflow triggers * ci(docs): remove unnecessary slash at build.yml * ci(docs): remove unnecessary slash at deploy_docs.yml * ci(docs): add docs/book.toml to deploy_docs trigger * ci(docs): Add schedule trigger * ci(docs): add github-pages cleaning * ci(docs): Exclude docs from generate_changelog * docs: Add dependencies installation script * ci(docs): Add mdbook pdf build * docs: Tweak Justfile to support pdf generation * Revert "docs: Always fetch the highest quality image by fetch_discourse_md" This reverts commit74130ee1fe. * ci(docs): Exclude deploy_docs.yml from cache-mdbook keys * docs: Add 'mdbook_build' to Justfile * docs: Add 'mdbook_serve' to Justfile * docs: Add debug flag to fetch_discourse_md * docs: Automate discourse documentation scrapping * docs: Add flock to fetch_discourse_md * docs: Add translation file generation with Justfile * docs: Prefix url replacements with site-url in replace-urls.py preprocessor * docs: Add installation guides docs: Replace print button * Revert "docs: Prefix url replacements with site-url in replace-urls.py preprocessor" This reverts commita685de4dce. * Reapply "docs: Prefix url replacements with site-url in replace-urls.py preprocessor" This reverts commit777d8055ea. * docs: fix replace-urls.py * docs: fix fetch_discourse_md.py hitting discourse ip_10_secs_limit * ci(docs): Remove duplicate '/' in build translation step * ci(docs): Update actions/cache * ci(docs): Reduce deploy_docs schedule timespan between triggers * docs: update install-deps.sh * docs: Update Advanced docs * docs: Add favicon * docs: Reword unstable documentation warning * docs: Change default theme to 'navy' * ci(docs): Move permisions to job scope * docs: refactor fetch_discourse_md.py Now it will export the function 'fetch', which other python scripts can use * docs: Add mkdocs skeleton * docs: Add cmdrun hook * ci(docs): Migrade deploy_docs to use mkdocs * chore: remove mdbook leftover files * docs: add support for markdown emojies * docs: add support for i18n translations to mkdocs * docs: add resource prefetching * docs: enable navigation indexes in toc * docs: add unstable documentation warning * docs: normalize toc docs: Add markdown magiclinks * docs: remove unnecesary extensions * ci(docs): Separate docs build into its own action * ci(docs): fix build docs action * ci(docs): Add default parameters to build_mkdocs action * ci(docs): Clean up leftover mdbook files * docs: remove leftover mkdocs-print-site-plugin * chore: add mkdocs offline documentation * docs: fix list indentation * ci(docs): Add github links to mkdocs * ci(docs): Add github authors to mkdocs * docs: Update documentation guide and scripts to mkdocs * docs: Add cache capabilities to cmdrun hook * docs: Enable instant loading docs: Enable toc in sidebar * docs: Update summary and add more posts * docs: Add mkdocs-material social plugin * docs: Disable instant loading * docs: Fix section url * docs: Fix fetch_discourse not fetching images properly * docs: Disable warning for using absolute links * docs: Add url replacement hook * docs: Restore 'General' section * docs: Remove aditional languages for now * docs: Add missing page titles * docs: move and rename index.md to docs/src/Handheld_and_HTPC_edition/Steam_Gaming_Mode.md * docs: remove leftover Bazzite_resources.md * docs: Add time fallback to git-revision-date * docs: Add navigation tabs * docs: Clear cmdrun cache with Justfile * docs: Add missing dual-boot guide url * docs: Change to a shorter section name for handheld and HTPC * docs: Add embed_youtube hook * docs: Remove leftover resources entry in index docs: Fix outdated 'Steam Gaming Overview' link in index * docs: Limit vertical image size * docs: add more url replacements * docs: Enable search features
182 lines
6.1 KiB
Python
182 lines
6.1 KiB
Python
import hashlib
|
|
import os
|
|
from pathlib import Path
|
|
import sys
|
|
from mkdocs.config.defaults import MkDocsConfig
|
|
from mkdocs import plugins
|
|
from mkdocs.structure.pages import Page
|
|
from mkdocs.structure.files import Files
|
|
|
|
sys.path.append(os.path.dirname(os.path.abspath(__file__)))
|
|
from copy import copy
|
|
import re
|
|
from fetch_discourse_md import fetch as fetch_md_discourse
|
|
|
|
|
|
########################### ONLY MODIFY THIS ###########################
|
|
URL_MAPPINGS = [
|
|
# region GENERAL
|
|
( # src/index.md
|
|
"https://universal-blue.discourse.group/docs?topic=561",
|
|
"/",
|
|
),
|
|
( # src/General/reporting_bugs.md
|
|
"https://universal-blue.discourse.group/docs?topic=3402",
|
|
"/General/reporting_bugs",
|
|
),
|
|
# region INSTALLATION GUIDE
|
|
( # src/General/Installation_Guide/Installing_Bazzite_for_HTPC_Setups.md
|
|
"https://universal-blue.discourse.group/docs?topic=1145",
|
|
"/General/Installation_Guide/Installing_Bazzite_for_HTPC_Setups/",
|
|
),
|
|
( # src/General/Installation_Guide/index.md
|
|
"https://universal-blue.discourse.group/docs?topic=35",
|
|
"/Installing_and_Managing_Software/",
|
|
),
|
|
( # src/General/Installation_Guide/dual_boot_setup_guide.md
|
|
"https://universal-blue.discourse.group/docs?topic=2743",
|
|
"/General/Installation_Guide/dual_boot_setup_guide/",
|
|
),
|
|
( # src/General/Installation_Guide/secure_boot.md
|
|
"https://universal-blue.discourse.group/docs?topic=2742",
|
|
"/General/Installation_Guide/secure_boot",
|
|
),
|
|
( # src/General/Installation_Guide/troubleshoot_guide.md
|
|
"https://universal-blue.discourse.group/docs?topic=2495",
|
|
"/General/Installation_Guide/troubleshoot_guide/",
|
|
),
|
|
# endregion INSTALLATION GUIDE
|
|
# endregion GENERAL
|
|
# region SOFTWARE
|
|
( # src/Installing_and_Managing_Software/Updates_Rollbacks_&_Rebasing/index.md
|
|
"https://universal-blue.discourse.group/docs?topic=36",
|
|
"/Installing_and_Managing_Software/Updates_Rollbacks_&_Rebasing/",
|
|
),
|
|
( # src/Installing_and_Managing_Software/Updates_Rollbacks_&_Rebasing/updating_guide.md
|
|
"https://universal-blue.discourse.group/docs?topic=2637",
|
|
"/Installing_and_Managing_Software/Updates_Rollbacks_&_Rebasing/updating_guide/",
|
|
),
|
|
( # src/Installing_and_Managing_Software/Updates_Rollbacks_&_Rebasing/rolling_back_system_updates.md
|
|
"https://universal-blue.discourse.group/docs?topic=2644",
|
|
"/Installing_and_Managing_Software/Updates_Rollbacks_&_Rebasing/rolling_back_system_updates/",
|
|
),
|
|
( # src/Installing_and_Managing_Software/Updates_Rollbacks_&_Rebasing/rebase_guide.md
|
|
"https://universal-blue.discourse.group/docs?topic=2646",
|
|
"/Installing_and_Managing_Software/Updates_Rollbacks_&_Rebasing/rebase_guide/",
|
|
),
|
|
( # src/Installing_and_Managing_Software/Updates_Rollbacks_&_Rebasing/bazzite_rollback_helper.md
|
|
"https://universal-blue.discourse.group/docs?topic=2647",
|
|
"/Installing_and_Managing_Software/Updates_Rollbacks_&_Rebasing/bazzite_rollback_helper/",
|
|
),
|
|
# endregion SOFTWARE
|
|
( # src/Gaming/index.md
|
|
"https://universal-blue.discourse.group/docs?topic=31",
|
|
"/Gaming/",
|
|
),
|
|
# region HTPC
|
|
( # src/Handheld_and_HTPC_edition/Handheld_Wiki/index.md
|
|
"https://universal-blue.discourse.group/docs?topic=1038",
|
|
"/Handheld_and_HTPC_edition/Handheld_Wiki/",
|
|
),
|
|
( # src/Handheld_and_HTPC_edition/Handheld_Wiki/Steam_Deck.md
|
|
"https://universal-blue.discourse.group/docs?topic=1849",
|
|
"/Handheld_and_HTPC_edition/Handheld_Wiki/Steam_Deck/",
|
|
),
|
|
( # src/Handheld_and_HTPC_edition/Steam_Gaming_Mode.md
|
|
"https://universal-blue.discourse.group/docs?topic=37",
|
|
"/Handheld_and_HTPC_edition/Steam_Gaming_Mode/",
|
|
),
|
|
# endregion HTPC
|
|
# region ADVANCED
|
|
(
|
|
# src/Advanced/Auto-Mounting_Secondary_Drives.md
|
|
"https://universal-blue.discourse.group/docs?topic=970",
|
|
"/Advanced/Auto-Mounting_Secondary_Drives/",
|
|
),
|
|
# endregion ADVANCED
|
|
]
|
|
|
|
########################################################################
|
|
|
|
|
|
CMDRUN_PATTERN = r"<!--\s?cmdrun\s+fetch_discourse_md\.py\s+\"(.*)\"\s*-->"
|
|
PLUGIN_NAME = os.path.basename(__file__).rstrip(".py")
|
|
|
|
plugin_cache_dir: str
|
|
|
|
|
|
def _cache_filename_generator(text: str) -> str:
|
|
"""Generate a sha265 encoded cache file path of a piece of text inside the plugin cache dir"""
|
|
cache_file = os.path.join(
|
|
plugin_cache_dir, hashlib.sha256(text.encode()).hexdigest()
|
|
)
|
|
return cache_file
|
|
|
|
|
|
def _fetch_callback(url: str):
|
|
cache_file = _cache_filename_generator(url)
|
|
if os.path.exists(cache_file):
|
|
return Path(cache_file).read_text().strip()
|
|
|
|
elif content := fetch_md_discourse(url):
|
|
with open(cache_file, "w+t") as c_file:
|
|
c_file.write(content)
|
|
return content
|
|
else:
|
|
return ""
|
|
|
|
|
|
def _cmdrun_sub_handler(match: re.Match) -> str:
|
|
print(match.group(1))
|
|
url = match.group(1)
|
|
result = _fetch_callback(url)
|
|
return result or ""
|
|
|
|
|
|
def on_config(config: MkDocsConfig):
|
|
"""Initialize cache dir"""
|
|
global plugin_cache_dir
|
|
plugin_cache_dir = os.path.join(
|
|
os.path.dirname(config.config_file_path), ".cache", PLUGIN_NAME
|
|
)
|
|
try:
|
|
os.makedirs(plugin_cache_dir, exist_ok=True)
|
|
except FileExistsError:
|
|
pass
|
|
|
|
|
|
@plugins.event_priority(100)
|
|
def _on_page_markdown_fetch_discourse(markdown: str, **kargs):
|
|
markdown_orig = markdown
|
|
result = copy(markdown_orig)
|
|
|
|
try:
|
|
result = re.sub(CMDRUN_PATTERN, _cmdrun_sub_handler, markdown_orig)
|
|
except Exception as err:
|
|
print("ERROR", err)
|
|
|
|
return result
|
|
|
|
|
|
@plugins.event_priority(99)
|
|
def _on_page_markdown_replace_urls(
|
|
markdown: str,
|
|
page: Page,
|
|
config: MkDocsConfig,
|
|
files: Files,
|
|
**kargs,
|
|
):
|
|
"""Replace discourse urls"""
|
|
res = markdown
|
|
for src, dst in URL_MAPPINGS:
|
|
if config.site_url:
|
|
dst = f"{config.site_url.rstrip("/")}/{dst.lstrip("/")}"
|
|
res = res.replace(src, dst)
|
|
return res
|
|
|
|
|
|
on_page_markdown = plugins.CombinedEvent(
|
|
_on_page_markdown_fetch_discourse,
|
|
_on_page_markdown_replace_urls,
|
|
)
|