mirror/bazzite
1
0
Fork 0
mirror of https://github.com/ublue-os/bazzite.git synced 2025-01-01 03:21:41 +00:00
Code Issues Packages Projects Releases Wiki Activity
3acbbd0c13
bazzite/docs/README.md

238 lines
7.0 KiB
Markdown
Raw Normal View History

feat: Prepare mdBook workflow for documentation (#1441) * 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 commit 6a781c659607e0c83c19248241684c5785c7e93b. * 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 commit 74130ee1fe9264dc7a4c4c49fb416ef3dc12e322. * 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 commit a685de4dce54debc900607d743069b79202a26ac. * Reapply "docs: Prefix url replacements with site-url in replace-urls.py preprocessor" This reverts commit 777d8055eac7543001200834939c960fb490e666. * 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
2024-08-21 18:56:12 +00:00
# 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](https://commonmark.org/help/).
---
The essential part that cant be missing in a mdBook is the `SUMMARY.md` file.
```md
<!-- 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**\*
<small>\* Just so you are aware </small>
---
## Transcribe Discourse docs to mdBooks
Requirements:
- Markdown compatible code editor (ex.: Visual Studio Code)
- mdBook (can be installed with Homebrew\*)
- Git
<small>\* If you are using Bazzite or [similar](https://universal-blue.org/), chances are that you already have it installed.</small>
---
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:
1. 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.
2. Our code editor.
3. A terminal open in the `docs` directory
```sh
$ cd docs
```
Get sure we have `fetch_discourse_md.py` in there, we will need it
```sh
$ 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.
1. Copy the URL of the document
2. In the terminal, pass the URL to `fetch_discourse_md.py`
```sh
$ ./utils/fetch_discourse_md.py "https://universal-blue.discourse.group/docs?topic=2743" | wl-copy
```
Normally, `fetch_discourse_md.py` would dump the resulting markdown doc in the terminal output, with `wl-copy` we store it in our clipboard for now.
3. 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 `_`
![](./src/img/doc_guide_filename.jpg)
### 4. Paste the document in the file
![](./src/img/doc_guide_paste.jpg)
### 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.
![](./src/img/doc_guide_discourse_url.jpg)
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
![](./src/img/doc_guide_rewrite_url.jpg)
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
```sh
mdbook serve --open
```
Now, more likely you wont find our new added post.
![](./src/img/doc_guide_where_did_go.jpg)
If you take a look at [the brief explanation](#brief-explanation-in-how-to-work-with-mdbook), you will read about `SUMMARY.md`. Files not listed in there wont be processed by mdBook.
Lets add our file there.
![](./src/img/doc_guide_add_summary.jpg)
And now our post is ready.
![](./src/img/doc_guide_there_you_are.jpg)
## Translate documentation
> ⚠️ WARNING
>
> It is better to start translation once [transcription](#transcribe-discourse-docs-to-mdbooks) is settled to keep up.
Translation isnt so straightforward as copying a markdown file and start working.
We rely in [mdbook-i18n-helpers](https://github.com/google/mdbook-i18n-helpers) for translation, which uses [GNU Gettext](https://www.gnu.org/software/gettext/manual/html_node/index.html).
We need some more dependencies in order to do translations, which can be installed with this script:
```sh
bash docs/utils/install-deps.sh
```
<details>
<summary>
<big>Dependencies list</big><br>
<sup>Ignore if using install-deps.sh</sup>
</summary>
- `.po` file editor (like [Poedit](https://flathub.org/apps/net.poedit.Poedit))
- Rust's `cargo` (you can install rust by running
`brew install rustup; rustup-init`)
- `mdbook-i18n-helpers` (after installing rust,
`cargo install mdbook-i18n-helpers`)
</details>
### 1. Basic preparation
Move to `docs`, then build the `.pot` file
```sh
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][ISO]. Per example, `es.po` would be an Spanish translation
file.
To add a new language to the documentation, follows these steps:
1. Get sure you did the [basic preparation](#1-basic-preparation-1)
2. Then run this, replacing `XX` with the [language code][ISO]:
```sh
just add_translation XX
```
In my case, I'm going to create an Spanish translation file:
```sh
just add_translation es
ls po/
# es.po messages.pot
```
### 3. Working with a translation file
![Poedit](./src/img/poedit.jpg)
We will now open that `.po` file with our po editor (in my case is Poedit).
We make some changes, hit <kbd>Ctrl</kbd>+<kbd>S</kbd> to save.
Lets see the changes we had done with a preview. Run this:
```sh
just preview_translation XX
```
In my case is `es`
```sh
just preview_translation es
```
And there it is!
![](./src/img/translation_example.jpg)
## Write new documentation
WIP
[ISO]: https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
Reference in New Issue Copy Permalink