Skip to content

Commit 98c1db9

Browse files
shima004shima004
committed
feat: Add versioning support and improve documentation localization
1 parent cad57bd commit 98c1db9

File tree

54 files changed

+4744
-13
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+4744
-13
lines changed

‎.github/workflows/document.yaml‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -54,13 +54,11 @@ jobs:
5454
- name: Build documentation
5555
run: |
5656
source .venv/bin/activate
57-
sphinx-apidoc -f -o ./docs/source ./adf_core_python
5857
cd docs
59-
make html
60-
ls build/html
58+
python build.py
6159
6260
- name: Deploy documentation
6361
uses: peaceiris/actions-gh-pages@v4
6462
with:
6563
github_token: ${{ secrets.GITHUB_TOKEN }}
66-
publish_dir: ./docs/build/html
64+
publish_dir: ./docs/pages

‎docs/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
source/adf_core_python.*
2+
pages

‎docs/build.py‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import os
2+
import subprocess
3+
import yaml
4+
5+
# a single build step, which keeps conf.py and versions.yaml at the main branch
6+
# in generall we use environment variables to pass values to conf.py, see below
7+
# and runs the build as we did locally
8+
def build_doc(version, language, tag):
9+
os.environ["current_version"] = version
10+
os.environ["current_language"] = language
11+
subprocess.run("git checkout " + tag, shell=True)
12+
subprocess.run("git checkout main -- conf.py", shell=True)
13+
subprocess.run("git checkout main -- versions.yaml", shell=True)
14+
subprocess.run("doxygen Doxyfile", shell=True)
15+
os.environ['SPHINXOPTS'] = "-D language='{}'".format(language)
16+
subprocess.run("make html", shell=True)
17+
18+
# a move dir method because we run multiple builds and bring the html folders to a
19+
# location which we then push to github pages
20+
def move_dir(src, dst):
21+
subprocess.run(["mkdir", "-p", dst])
22+
subprocess.run("mv "+src+'* ' + dst, shell=True)
23+
24+
# to separate a single local build from all builds we have a flag, see conf.py
25+
os.environ["build_all_docs"] = str(True)
26+
os.environ["pages_root"] = "http://127.0.0.1:5500/docs/pages"
27+
28+
# manually the main branch build in the current supported languages
29+
build_doc("latest", "en", "main")
30+
move_dir("./build/html/", "./pages/")
31+
build_doc("latest", "ja", "main")
32+
move_dir("./build/html/", "./pages/ja/")
33+
34+
# reading the yaml file
35+
with open("versions.yaml", "r") as yaml_file:
36+
docs = yaml.safe_load(yaml_file)
37+
38+
# and looping over all values to call our build with version, language and its tag
39+
# for version, details in docs.items():
40+
# tag = details.get('tag', '')
41+
# for language in details.get('languages', []):
42+
# build_doc(version, language, version)
43+
# move_dir("./build/html/", "./pages/"+version+'/'+language+'/')

‎docs/source/_templates/versions.html‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
<div
2+
class="rst-versions"
3+
data-toggle="rst-versions"
4+
role="note"
5+
aria-label="versions"
6+
>
7+
<span class="rst-current-version" data-toggle="rst-current-version">
8+
Language: {{ current_language }}
9+
<span class="fa fa-caret-down"></span>
10+
</span>
11+
<div class="rst-other-versions">
12+
{% if languages|length >= 1 %}
13+
<dl>
14+
<dt>{{ _('Languages') }}</dt>
15+
{% for the_language, url in languages %}
16+
<dd><a href="{{ url }}/index.html">{{ the_language }}</a></dd>
17+
{% endfor %}
18+
</dl>
19+
{% endif %}
20+
<!-- {% if versions|length >= 1 %}
21+
<dl>
22+
<dt>{{ _('Versions') }}</dt>
23+
{% for the_version, url in versions %}
24+
<dd><a href="{{ url }}/index.html">{{ the_version }}</a></dd>
25+
{% endfor %}
26+
</dl>
27+
{% endif %}
28+
<br>
29+
</dl> -->
30+
</div>
31+
</div>

‎docs/source/conf.py‎

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55

66
import os
77
import sys
8+
import yaml
89

910
sys.path.insert(0, os.path.abspath("../../"))
1011

@@ -32,10 +33,55 @@
3233
templates_path = ["_templates"]
3334
exclude_patterns = []
3435

35-
language = "ja"
3636

3737
# -- Options for HTML output -------------------------------------------------
3838
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
3939

40-
html_theme = "sphinx_book_theme"
40+
html_theme = "sphinx_rtd_theme"
4141
html_static_path = ["_static"]
42+
43+
locale_dirs = ["locale"]
44+
language = "en"
45+
46+
# get the environment variable build_all_docs and pages_root
47+
build_all_docs = os.environ.get("build_all_docs")
48+
pages_root = os.environ.get("pages_root", "")
49+
50+
# if not there, we dont call this
51+
if build_all_docs is not None:
52+
# we get the current language and version
53+
current_language = os.environ.get("current_language")
54+
current_version = os.environ.get("current_version")
55+
56+
# we set the html_context wit current language and version
57+
# and empty languages and versions for now
58+
html_context = {
59+
'current_language' : current_language,
60+
'languages' : [],
61+
'current_version' : current_version,
62+
'versions' : [],
63+
}
64+
65+
66+
# and we append all versions and langauges accordingly
67+
# we treat t he main branch as latest
68+
if (current_version == 'latest'):
69+
html_context['languages'].append(['en', pages_root])
70+
html_context['languages'].append(['ja', pages_root+'/ja'])
71+
72+
if (current_language == 'en'):
73+
html_context['versions'].append(['latest', pages_root])
74+
if (current_language == 'ja'):
75+
html_context['versions'].append(['latest', pages_root+'/ja'])
76+
77+
# and loop over all other versions from our yaml file
78+
# to set versions and languages
79+
with open("../versions.yaml", "r") as yaml_file:
80+
docs = yaml.safe_load(yaml_file)
81+
82+
if (current_version != 'latest'):
83+
for language in docs[current_version].get('languages', []):
84+
html_context['languages'].append([language, pages_root+'/'+current_version+'/'+language])
85+
86+
for version, details in docs.items():
87+
html_context['versions'].append([version, pages_root+'/'+version+'/'+current_language])

‎docs/source/index.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,11 @@ adf-core-pythonのドキュメント
1414

1515
パッケージとしてまだ公開していないため、pip でインストールすることはできません。
1616

17+
.. warning::
18+
19+
以下の言語のドキュメントは機械翻訳を使用しています。翻訳の正確性については保証できません。
20+
英語
21+
1722

1823
概要
1924
----

‎docs/source/locale/en/LC_MESSAGES/adf_core_python.cli.po‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# SOME DESCRIPTIVE TITLE.
2+
# Copyright (C) 2024, Haruki Uehara, Yuki Shimada
3+
# This file is distributed under the same license as the adf-core-python
4+
# package.
5+
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
6+
#
7+
#, fuzzy
8+
msgid ""
9+
msgstr ""
10+
"Project-Id-Version: adf-core-python \n"
11+
"Report-Msgid-Bugs-To: \n"
12+
"POT-Creation-Date: 2024-12-19 13:59+0900\n"
13+
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
14+
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
15+
"Language: en\n"
16+
"Language-Team: en <[email protected]>\n"
17+
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
18+
"MIME-Version: 1.0\n"
19+
"Content-Type: text/plain; charset=utf-8\n"
20+
"Content-Transfer-Encoding: 8bit\n"
21+
"Generated-By: Babel 2.16.0\n"
22+
23+
#: ../../source/adf_core_python.cli.rst:2
24+
msgid "adf\\_core\\_python.cli package"
25+
msgstr ""
26+
27+
#: ../../source/adf_core_python.cli.rst:5
28+
msgid "Submodules"
29+
msgstr ""
30+
31+
#: ../../source/adf_core_python.cli.rst:8
32+
msgid "adf\\_core\\_python.cli.cli module"
33+
msgstr ""
34+
35+
#: ../../source/adf_core_python.cli.rst:16
36+
msgid "Module contents"
37+
msgstr ""
38+

‎docs/source/locale/en/LC_MESSAGES/adf_core_python.core.agent.action.ambulance.po‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# SOME DESCRIPTIVE TITLE.
2+
# Copyright (C) 2024, Haruki Uehara, Yuki Shimada
3+
# This file is distributed under the same license as the adf-core-python
4+
# package.
5+
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
6+
#
7+
#, fuzzy
8+
msgid ""
9+
msgstr ""
10+
"Project-Id-Version: adf-core-python \n"
11+
"Report-Msgid-Bugs-To: \n"
12+
"POT-Creation-Date: 2024-12-19 13:59+0900\n"
13+
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
14+
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
15+
"Language: en\n"
16+
"Language-Team: en <[email protected]>\n"
17+
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
18+
"MIME-Version: 1.0\n"
19+
"Content-Type: text/plain; charset=utf-8\n"
20+
"Content-Transfer-Encoding: 8bit\n"
21+
"Generated-By: Babel 2.16.0\n"
22+
23+
#: ../../source/adf_core_python.core.agent.action.ambulance.rst:2
24+
msgid "adf\\_core\\_python.core.agent.action.ambulance package"
25+
msgstr ""
26+
27+
#: ../../source/adf_core_python.core.agent.action.ambulance.rst:5
28+
msgid "Submodules"
29+
msgstr ""
30+
31+
#: ../../source/adf_core_python.core.agent.action.ambulance.rst:8
32+
msgid "adf\\_core\\_python.core.agent.action.ambulance.action\\_load module"
33+
msgstr ""
34+
35+
#: adf_core_python.core.agent.action.ambulance.action_load.ActionLoad:1
36+
#: adf_core_python.core.agent.action.ambulance.action_rescue.ActionRescue:1
37+
#: adf_core_python.core.agent.action.ambulance.action_unload.ActionUnload:1 of
38+
msgid "Bases: :py:class:`~adf_core_python.core.agent.action.action.Action`"
39+
msgstr ""
40+
41+
#: ../../source/adf_core_python.core.agent.action.ambulance.rst:16
42+
msgid "adf\\_core\\_python.core.agent.action.ambulance.action\\_rescue module"
43+
msgstr ""
44+
45+
#: ../../source/adf_core_python.core.agent.action.ambulance.rst:24
46+
msgid "adf\\_core\\_python.core.agent.action.ambulance.action\\_unload module"
47+
msgstr ""
48+
49+
#: ../../source/adf_core_python.core.agent.action.ambulance.rst:32
50+
msgid "Module contents"
51+
msgstr ""
52+

‎docs/source/locale/en/LC_MESSAGES/adf_core_python.core.agent.action.common.po‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# SOME DESCRIPTIVE TITLE.
2+
# Copyright (C) 2024, Haruki Uehara, Yuki Shimada
3+
# This file is distributed under the same license as the adf-core-python
4+
# package.
5+
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
6+
#
7+
#, fuzzy
8+
msgid ""
9+
msgstr ""
10+
"Project-Id-Version: adf-core-python \n"
11+
"Report-Msgid-Bugs-To: \n"
12+
"POT-Creation-Date: 2024-12-19 13:59+0900\n"
13+
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
14+
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
15+
"Language: en\n"
16+
"Language-Team: en <[email protected]>\n"
17+
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
18+
"MIME-Version: 1.0\n"
19+
"Content-Type: text/plain; charset=utf-8\n"
20+
"Content-Transfer-Encoding: 8bit\n"
21+
"Generated-By: Babel 2.16.0\n"
22+
23+
#: ../../source/adf_core_python.core.agent.action.common.rst:2
24+
msgid "adf\\_core\\_python.core.agent.action.common package"
25+
msgstr ""
26+
27+
#: ../../source/adf_core_python.core.agent.action.common.rst:5
28+
msgid "Submodules"
29+
msgstr ""
30+
31+
#: ../../source/adf_core_python.core.agent.action.common.rst:8
32+
msgid "adf\\_core\\_python.core.agent.action.common.action\\_move module"
33+
msgstr ""
34+
35+
#: adf_core_python.core.agent.action.common.action_move.ActionMove:1
36+
#: adf_core_python.core.agent.action.common.action_rest.ActionRest:1 of
37+
msgid "Bases: :py:class:`~adf_core_python.core.agent.action.action.Action`"
38+
msgstr ""
39+
40+
#: ../../source/adf_core_python.core.agent.action.common.rst:16
41+
msgid "adf\\_core\\_python.core.agent.action.common.action\\_rest module"
42+
msgstr ""
43+
44+
#: ../../source/adf_core_python.core.agent.action.common.rst:24
45+
msgid "Module contents"
46+
msgstr ""
47+

‎docs/source/locale/en/LC_MESSAGES/adf_core_python.core.agent.action.fire.po‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# SOME DESCRIPTIVE TITLE.
2+
# Copyright (C) 2024, Haruki Uehara, Yuki Shimada
3+
# This file is distributed under the same license as the adf-core-python
4+
# package.
5+
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
6+
#
7+
#, fuzzy
8+
msgid ""
9+
msgstr ""
10+
"Project-Id-Version: adf-core-python \n"
11+
"Report-Msgid-Bugs-To: \n"
12+
"POT-Creation-Date: 2024-12-19 13:59+0900\n"
13+
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
14+
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
15+
"Language: en\n"
16+
"Language-Team: en <[email protected]>\n"
17+
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
18+
"MIME-Version: 1.0\n"
19+
"Content-Type: text/plain; charset=utf-8\n"
20+
"Content-Transfer-Encoding: 8bit\n"
21+
"Generated-By: Babel 2.16.0\n"
22+
23+
#: ../../source/adf_core_python.core.agent.action.fire.rst:2
24+
msgid "adf\\_core\\_python.core.agent.action.fire package"
25+
msgstr ""
26+
27+
#: ../../source/adf_core_python.core.agent.action.fire.rst:5
28+
msgid "Submodules"
29+
msgstr ""
30+
31+
#: ../../source/adf_core_python.core.agent.action.fire.rst:8
32+
msgid "adf\\_core\\_python.core.agent.action.fire.action\\_extinguish module"
33+
msgstr ""
34+
35+
#: adf_core_python.core.agent.action.fire.action_extinguish.ActionExtinguish:1
36+
#: adf_core_python.core.agent.action.fire.action_refill.ActionRefill:1
37+
#: adf_core_python.core.agent.action.fire.action_rescue.ActionRescue:1 of
38+
msgid "Bases: :py:class:`~adf_core_python.core.agent.action.action.Action`"
39+
msgstr ""
40+
41+
#: ../../source/adf_core_python.core.agent.action.fire.rst:16
42+
msgid "adf\\_core\\_python.core.agent.action.fire.action\\_refill module"
43+
msgstr ""
44+
45+
#: ../../source/adf_core_python.core.agent.action.fire.rst:24
46+
msgid "adf\\_core\\_python.core.agent.action.fire.action\\_rescue module"
47+
msgstr ""
48+
49+
#: ../../source/adf_core_python.core.agent.action.fire.rst:32
50+
msgid "Module contents"
51+
msgstr ""
52+

0 commit comments

Comments
 (0)