Skip to content

Latest commit

 

History

History
109 lines (73 loc) · 2.93 KB

README.md

File metadata and controls

109 lines (73 loc) · 2.93 KB
Raw

backend.ai-docs-webui

User's guide for Backend.AI GUI Console.

Setup build environment

We use poetry to manage dependencies and packaging. Poetry can be installed by the following command.

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python
source ~/.poetry/env  # == export PATH="$HOME/.poetry/bin:$PATH"

We recommend to use virtualenv. After virtualenv setup, run following command to install dependent packages.

poetry install

Build documents

To build html documentation, run following command in the docs directory. All commands should be executed under poetry's virtual environment. For example, you can run poetry shell to enter a command shell with virtualenv.

make html

Built documents will be located under docs/_build.

Translation

When English document is updated, extract translatable messages into .pot files. Go to docs directory and run following command.

make gettext

From those .pot files, .po message catalogs can be generated:

sphinx-intl update -p _build/gettext -l ko

Now, .po files are generated in locale/ko/LC_MESSAGES/. Translate messages with them. For eaiser .po translation, you may use GUI apps like POEDIT. Or, you may refef to translate_po.py for auto translation using external LLM services.

Note that a Korean character should not be followed by two backticks(``) WITHOUT A SPACE, since that will raise compilation errors.

After translation, run following to build translated html document.

make -e SPHINXOPTS="-D language='ko'" html

To see the local html documents:

open _build/html/index.html

Build PDF document

To build a pdf document, just replace html to latexpdf. Note, however, that your local machine should be prepared with latex generation environment, such as MacTex, to make pdf file. The following is a brief preparation steps in Mac:

  • Install MacTex.
  • Register the path to texbin: export PATH="$PATH:/Library/Tex/texbin".
  • Install fonts on the mac for PDF generation. Fonts can be found at docs/_static/fonts.

If prepration is done, execute the following command to generate a pdf document.

cd docs
./build_pdf.sh <language-code:en|ko|th|...>

The generated PDF is located under _build/.

Example of building PDF document via LLM

This is AI era, so we provide an example to machine-translate and build Japanese (ja) PDF document here for reference:

cd docs
make gettext
sphinx-intl update -p _build/gettext -l ja
find docs/locale/ja/LC_MESSAGES -name "*.po" -type f | xargs -I {} sh -c 'python ../translate_po.py "{}" "{}"'
# Configurating latexpdf build configs (in conf.py) may take some time.
./build_pdf.sh ja

References for newcomers

http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html