Skip to content

Commit 4ced4d1

Browse files
ianychoiianychoi
authored
Merge pull request #1 from ianychoi/main
Discussed with @ppiyakk2 @Eundms @wonyongg
2 parents 2bf7779 + 2e3571c commit 4ced4d1

42 files changed

Lines changed: 1940 additions & 0 deletions

Some content is hidden

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

‎.github/workflows/docs.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: docs
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
9+
# GitHub Pages 배포에 필요한 최소 권한.
10+
permissions:
11+
contents: read
12+
13+
# 동시 배포 충돌 방지 (진행 중 실행은 취소하지 않음).
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build-docs:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- uses: actions/setup-python@v5
25+
with:
26+
python-version: '3.12'
27+
28+
- name: Install tox
29+
run: python -m pip install --upgrade pip tox
30+
31+
- name: Lint docs (doc8)
32+
run: tox -e pep8
33+
34+
- name: Build docs (sphinx)
35+
run: tox -e docs
36+
37+
- name: Upload Pages artifact
38+
uses: actions/upload-pages-artifact@v3
39+
with:
40+
path: doc/build/html
41+
42+
deploy:
43+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
44+
needs: build-docs
45+
runs-on: ubuntu-latest
46+
permissions:
47+
pages: write
48+
id-token: write
49+
environment:
50+
name: github-pages
51+
url: ${{ steps.deployment.outputs.page_url }}
52+
steps:
53+
- name: Deploy to GitHub Pages
54+
id: deployment
55+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Sphinx / documentation build output
2+
doc/build/
3+
doc/source/_build/
4+
releasenotes/build/
5+
*.doctree
6+
*.pickle
7+
8+
# tox / local virtual environments
9+
.tox/
10+
.nox/
11+
.venv/
12+
venv/
13+
env/
14+
ENV/
15+
16+
# Python cache, test, and packaging output
17+
__pycache__/
18+
*.py[cod]
19+
*$py.class
20+
*.so
21+
.cache/
22+
.pytest_cache/
23+
.coverage
24+
.coverage.*
25+
coverage.xml
26+
htmlcov/
27+
cover/
28+
build/
29+
dist/
30+
*.egg-info/
31+
.eggs/
32+
pip-wheel-metadata/
33+
34+
# OpenStack-style generated files
35+
AUTHORS
36+
ChangeLog
37+
.stestr/
38+
.testrepository/
39+
40+
# Kubernetes-style local output
41+
_output/
42+
bazel-*
43+
*.test
44+
*.out
45+
coverage.out
46+
47+
# Local configuration and logs
48+
.env
49+
.env.*
50+
!.env.example
51+
*.log
52+
53+
# Editor / OS files
54+
.DS_Store
55+
Thumbs.db
56+
*~
57+
*.swp
58+
*.swo
59+
.idea/
60+
.vscode/

‎CONTRIBUTING.rst‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
==================
2+
Contributing Guide
3+
==================
4+
5+
Thank you for your interest in this project. Since one of its goals is to
6+
learn the conventions of the OpenStack documentation ecosystem, the
7+
contribution workflow also follows the approach of the `OpenStack
8+
Documentation Contributor Guide
9+
<https://docs.openstack.org/doc-contrib-guide/>`_. The one difference is that
10+
code review and CI use **GitHub Pull Requests** and **GitHub Actions** instead
11+
of Gerrit and Zuul.
12+
13+
14+
Before you start
15+
================
16+
17+
#. Fork this repository and clone it locally.
18+
#. Install Python 3.10+ and `tox <https://tox.wiki/>`_.
19+
#. Confirm that the documentation builds:
20+
21+
.. code-block:: console
22+
23+
$ tox -e docs
24+
25+
26+
Workflow
27+
========
28+
29+
#. **Find or open an issue**: Check whether an issue already exists for the
30+
work you want to do, and open one if needed to share your intent.
31+
#. **Create a branch**: Branch from ``main``. Branch names in the form
32+
``docs/<topic>`` or ``fix/<topic>`` are recommended.
33+
#. **Write documentation**: Add or edit rST documents in the appropriate place
34+
under ``doc/source/``. When you add a new page, always register it in the
35+
parent ``index.rst`` ``toctree``.
36+
#. **Build and lint locally**:
37+
38+
.. code-block:: console
39+
40+
$ tox -e docs
41+
$ tox -e pep8
42+
43+
#. **Commit**: A one-line summary (about 50 characters) followed by a body is
44+
recommended.
45+
#. **Open a pull request**: Send a PR to ``main`` from your fork. GitHub
46+
Actions will automatically validate the documentation build.
47+
#. **Address review feedback**: Update the PR to reflect reviewer feedback.
48+
49+
50+
reStructuredText conventions
51+
============================
52+
53+
* Keep one sentence per line where possible, and keep line length under 79
54+
characters (the ``doc8`` lint default).
55+
* Section title underlines must be at least as long as the title text. Note
56+
that CJK (full-width) characters count as width 2, so make underlines
57+
generously long for titles that contain them.
58+
* Use heading levels consistently within a document. The recommended order in
59+
this project is:
60+
61+
.. code-block:: rst
62+
63+
======
64+
Title 1 (document title, overline and underline)
65+
======
66+
67+
Title 2
68+
=======
69+
70+
Title 3
71+
-------
72+
73+
Title 4
74+
~~~~~~~
75+
76+
* Use admonition directives such as note and warning:
77+
78+
.. code-block:: rst
79+
80+
.. note::
81+
82+
Something worth noting.
83+
84+
* Prefer explicit hyperlinks for external links, and connect terminology to
85+
the glossary in ``doc/source/glossary.rst``.
86+
87+
88+
Documentation style guide
89+
==========================
90+
91+
* **Translated documents**: Convey the meaning of the source (English) text
92+
accurately while prioritizing natural Korean prose. When a technical term
93+
first appears, write it as ``한글(English)``.
94+
* **Proper nouns / project names**: Keep the original spelling for names such
95+
as OpenStack, Kubernetes, Nova, and Neutron.
96+
* **Commands / code**: Specify the appropriate language for ``code-block``
97+
directives (``console``, ``yaml``, ``bash``, etc.).
98+
99+
For detailed rST/Sphinx conventions, see the ``doc/source/documentation/``
100+
section.
101+
102+
103+
Code of Conduct
104+
===============
105+
106+
This project aims to be an open and respectful community. All participants are
107+
encouraged to follow the spirit of the `OpenStack Community Code of Conduct
108+
<https://www.openstack.org/legal/community-code-of-conduct/>`_.

‎README.rst‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
========================================================================
2+
OpenStack & Kubernetes Operations Documentation and Internationalization
3+
========================================================================
4+
5+
.. image:: https://github.com/infra-cloud-kr/openstack-kubernetes/actions/workflows/docs.yml/badge.svg
6+
:target: https://github.com/infra-cloud-kr/openstack-kubernetes/actions/workflows/docs.yml
7+
:alt: Documentation build status
8+
9+
This project documents how to install and operate the two leading global
10+
open source infrastructure projects — **Kubernetes** and **OpenStack** — along
11+
with their best practices, and contributes to the internationalization (i18n)
12+
of the related upstream technical documentation, including its translation
13+
into Korean.
14+
15+
Just as the two communities formally met through SIGs (Special Interest
16+
Groups) to drive technical integration, their documentation localization
17+
efforts run in parallel: the **OpenStack I18n SIG** and the **Kubernetes
18+
SIG Docs localization subproject**. This project sits at the meeting point of
19+
these two localization communities and aims to experience both of their
20+
Korean localization workflows.
21+
22+
Following the conventions of the OpenStack documentation ecosystem, the
23+
repository is built with `Sphinx <https://www.sphinx-doc.org/>`_ and
24+
reStructuredText (rST), built via `tox <https://tox.wiki/>`_, and validated by
25+
GitHub Actions. The goal goes beyond simply writing documents: contributors
26+
also gain hands-on experience with the OpenStack-style documentation
27+
contribution workflow (rST/Sphinx, reviewable PRs, CI-based quality checks).
28+
29+
.. note::
30+
31+
The documentation is currently an initial skeleton. The body of each
32+
section is intended to be filled in incrementally (see the ``note`` / TODO
33+
markers in each document).
34+
35+
36+
Goals
37+
=====
38+
39+
The project centers on **"hands-on Korean localization"**:
40+
41+
* Document installation, operation, and best practices for the *OpenStack on
42+
Kubernetes* and *Kubernetes on OpenStack* environments, based on real
43+
experience building and operating them. Beyond understanding the two
44+
projects, contributors practice documenting in a way that follows global
45+
norms, building the fundamentals needed to contribute to upstream open
46+
source projects.
47+
* Select the upstream documents referenced along the way and aim for 100%
48+
Korean localization. This includes setting up a translation platform such
49+
as Weblate and organizing know-how on AI-assisted translation, leaving a
50+
meaningful footprint in global open source documentation and i18n while
51+
translating with first-hand understanding of both technologies.
52+
53+
54+
Documentation layout
55+
=====================
56+
57+
The documentation source lives under ``doc/source/`` and is organized into the
58+
following sections.
59+
60+
* **introduction** — why the two technologies are used together, the history
61+
and present of SIG activities, and a suggested learning path
62+
* **OpenStack on Kubernetes** — running the OpenStack control plane on top of
63+
Kubernetes using openstack-helm, Kolla, and more
64+
* **Kubernetes on OpenStack** — running Kubernetes on top of OpenStack using
65+
Magnum, cloud-provider-openstack, Cinder CSI, the Octavia load balancer,
66+
and more
67+
* **storage** — integrating Cinder, Swift, and Ceph with Kubernetes
68+
* **labs** — step-by-step hands-on guides
69+
* **documentation** — rST/Sphinx basics, OpenStack/Kubernetes documentation
70+
conventions, and review guidelines
71+
* **translation-i18n** — how the two Korean localization communities (the
72+
OpenStack I18n SIG and the Kubernetes SIG Docs localization subproject) are
73+
organized, plus OpenStack i18n, Kubernetes localization, Weblate, and
74+
AI-assisted translation workflows
75+
76+
77+
Building locally
78+
================
79+
80+
With `tox <https://tox.wiki/>`_ installed, build the HTML documentation with:
81+
82+
.. code-block:: console
83+
84+
$ tox -e docs
85+
86+
The output is generated under ``doc/build/html/``. Open
87+
``doc/build/html/index.html`` in a browser to review it.
88+
89+
To build directly without tox:
90+
91+
.. code-block:: console
92+
93+
$ python -m venv .venv
94+
$ . .venv/bin/activate
95+
$ pip install -r doc/requirements.txt
96+
$ sphinx-build -W -b html doc/source doc/build/html
97+
98+
To lint the rST sources:
99+
100+
.. code-block:: console
101+
102+
$ tox -e pep8
103+
104+
105+
Contributing
106+
============
107+
108+
See `CONTRIBUTING.rst <CONTRIBUTING.rst>`_ for how to contribute.
109+
110+
111+
License
112+
=======
113+
114+
This project is licensed under the `Apache License 2.0 <LICENSE>`_.

‎doc/requirements.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# 문서 빌드에 필요한 Python 패키지.
2+
# 처음에는 기본 theme(alabaster)로 단순하게 시작합니다.
3+
# 추후 openstackdocstheme 로 전환하려면 conf.py 의 html_theme 을 함께 변경하세요.
4+
sphinx>=7.0.0
5+
doc8>=1.1.0
6+
7+
# (선택) OpenStack 공식 문서 테마로 전환할 때 주석을 해제하세요.
8+
# openstackdocstheme>=3.0.0

0 commit comments

Comments
 (0)