181497bc17
* 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
7.0 KiB
Contributing to Bazzite mdBook documentation
Introduction
This is a guide that will show you:
- How to write new documentation pages in mdBooks.
- How to transcribe documentation, from Discourse forums (https://universal-blue.discourse.group/) to mdBook pages.
Brief explanation in how to work with mdBook
mdBook is a command line tool to create books with Markdown. It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean, easily navigable and customizable presentation
Source ~ https://rust-lang.github.io/mdBook/
TL;DR: Its a fancy way tool that allows us to create a documentation website with basic Markdown.
The essential part that cant be missing in a mdBook is the SUMMARY.md file.
<!-- Example of SUMMARY.md contents -->
# General
- [📜 Bazzite's README](Bazzite_README.md)
- [❓️ FAQ](General/FAQ.md)
- [📖 Installation Guide](General/Installation_Guide/index.md)
- [📝 Desktop Environment Tweaks](General/Desktop_Environment_Tweaks.md)
- [🤝 Contributing to Bazzite](General/Contributing_to_Bazzite.md)
- [🎲 Gaming](Gaming/index.md)
- [Game Launchers](Gaming/Game_Launchers.md)
# Steam Gaming Mode / Handheld & HTPC Hardware
- [📺️ Steam Gaming Mode Overview](Handheld_and_HTPC_edition/Steam_Gaming_Mode/index.md)
- [Change Physical Keyboard Layout for Steam Gaming Mode](Handheld_and_HTPC_edition/Change_Physical_Keyboard_Layout_for_Steam_Gaming_Mode.md)
SUMMARY.md acts not only as a nice looking table of contents, but as indexer as well.
If a page is not listed in SUMMARY.md, it wont be included in the mdBook*
* Just so you are aware
Transcribe Discourse docs to mdBooks
Requirements:
- Markdown compatible code editor (ex.: Visual Studio Code)
- mdBook (can be installed with Homebrew*)
- Git
* If you are using Bazzite or similar, chances are that you already have it installed.
Best way to learn is with a real life example. We will transcribe https://universal-blue.discourse.group/docs?topic=2743
1. Basic preparation
We will start with getting our utilities ready:
-
A web browser with the Discourse doc page we want to transcribe. We will use https://universal-blue.discourse.group/docs?topic=2743 for this example.
-
Our code editor.
-
A terminal open in the
docsdirectory$ cd docsGet sure we have
fetch_discourse_md.pyin there, we will need it$ ls ./utils/fetch_discourse_md.py ./utils/fetch_discourse_md.py
2. Copy the post
fetch_discourse_md.py is your friend for this task.
-
Copy the URL of the document
-
In the terminal, pass the URL to
fetch_discourse_md.py$ ./utils/fetch_discourse_md.py "https://universal-blue.discourse.group/docs?topic=2743" | wl-copyNormally,
fetch_discourse_md.pywould dump the resulting markdown doc in the terminal output, withwl-copywe store it in our clipboard for now. -
Create the markdown file where we will store our document. The title of the post is "Dual Boot Preliminary Setup and Post-Setup Guide", so somewhere under "Advanced" should be fitting.
⚠️ WARNING
Just remember, ⚠️DO NOT USE SPACES IN THE FILE NAME⚠️. Is really important, spaces in filenames is going to bit us later in a future. Instead, use underscores
_
4. Paste the document in the file
5. Rewrite URLs
We are almost done. The problem is fetch_discourse_md.py only will give us a dumped version of the Discourse document.
There is posibly URLs that are pointing to other documentation posts in Discourse that we might have already in our mdBook.
The url in the image above is pointing to the Steam Gaming Mode Overview (Handheld/HTPC) post. At the time of writting this, we have that post avaliable in our mdBook, so we can simply replace that URL with ours
In our case, the post is located in ../Handheld_and_HTPC_edition/Steam_Gaming_Mode/index.md
6. Link back in SUMMARY.md
We can check how our post looks in mdBook, run in the terminal
mdbook serve --open
Now, more likely you wont find our new added post.
If you take a look at the brief explanation, you will read about SUMMARY.md. Files not listed in there wont be processed by mdBook.
Lets add our file there.
And now our post is ready.
Translate documentation
⚠️ WARNING
It is better to start translation once transcription is settled to keep up.
Translation isnt so straightforward as copying a markdown file and start working.
We rely in mdbook-i18n-helpers for translation, which uses GNU Gettext.
We need some more dependencies in order to do translations, which can be installed with this script:
bash docs/utils/install-deps.sh
Dependencies list
Ignore if using install-deps.sh
.pofile editor (like Poedit)- Rust's
cargo(you can install rust by runningbrew install rustup; rustup-init) mdbook-i18n-helpers(after installing rust,cargo install mdbook-i18n-helpers)
1. Basic preparation
Move to docs, then build the .pot file
cd docs
just build_messages_pot
This will create po/messages.pot, which acts as an index of text fragments
from all our markdown files.
2. (Optional) Add a new language
All translations files are stored in docs/po/ in the form of xx.po files, xx referencing the language code following ISO 639. Per example, es.po would be an Spanish translation
file.
To add a new language to the documentation, follows these steps:
-
Get sure you did the basic preparation
-
Then run this, replacing
XXwith the language code:just add_translation XXIn my case, I'm going to create an Spanish translation file:
just add_translation es ls po/ # es.po messages.pot
3. Working with a translation file
We will now open that .po file with our po editor (in my case is Poedit).
We make some changes, hit Ctrl+S to save.
Lets see the changes we had done with a preview. Run this:
just preview_translation XX
In my case is es
just preview_translation es
And there it is!
Write new documentation
WIP