Repository navigation
Unify writing style and terminology across the docs - #51
Merged
Merged
Conversation
The pages had drifted into two Korean writing styles and several spellings for the same thing, so they read like they came from different projects. Move the four remaining 한다체 documents to 합니다체 and leave the glossary in its dictionary style. Put a space between a Latin word and the Korean particle that follows it, the way most of the docs already did. Settle on the glossary headwords for Pod, VM, Octavia, openstack-helm and Kubernetes. ovn-ovs and openstack-helm-network-outline used '-' for their top-level sections, which contradicts CONTRIBUTING, so promote them to '=' and size every title decoration to the width of its title. Point the eight redirecting links at their final URLs, turn two sentences wrapped in inline literals into bold text, replace the one :code: role with an inline literal, and let the numbered list number itself. Add the terms the newer pages already use - libvirt, KVM, QEMU, cgroup, VXLAN, ML2, Placement, Horizon, Calico, Kubespray, kOps, amphora - to the glossary and link first mentions with :term:. The longest pages were reachable only through a toctree, so link them from the documents that lead into them. Rewrite the CSI component section, which listed kubelet as a CSI component and lost a sentence along the way. It is the controller and node plugins, with kubelet calling the node plugin over a UNIX socket.
Nothing checked the conventions the docs were meant to follow, so the same inconsistencies kept coming back. Add a linkcheck tox environment and run it in CI without failing the build, so broken links and redirects surface on their own. Write the Korean prose rules - sentence style, particle spacing, term notation on first use, preferred spellings - along with the markup and link rules into CONTRIBUTING, and add the matching items to the contributor and reviewer checklists. Drop sphinx.ext.intersphinx and its empty mapping; a comment says how to turn it back on when there is something to point at.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
개요
CONTRIBUTING.rst와 리뷰 체크리스트에 명문화했습니다.표기 통일
kubernetes-csi,openstack-fundamentals,cni-and-neutron,neutron-helm-chart)를 합니다체로 맞췄습니다.glossary.rst는 사전체라 그대로 두었습니다.폭이 2로), 슬래시 복합어(CPU/메모리)는 제외했습니다.파드→Pod,가상 머신→VM,옥타비아→Octavia,OpenStack-Helm/OSH→openstack-helm,K8s→Kubernetes로 용어집 표제어에 맞췄습니다.한글(English, ABBR)형식으로 통일했습니다.구조
ovn-ovs,openstack-helm-network-outline이 최상위 절에-를 쓰고 있어CONTRIBUTING.rst규정대로=로 고쳤고, 제목 밑줄 길이를 제목 폭에 맞췄습니다.:term:을 걸었습니다. (15회/3개 문서 → 41회/11개 문서)toctree말고는 도달 경로가 없어서, 관련 문서에서:doc:로 연결했습니다. (인바운드 링크 0인 문서 15개 → 0개)수정
docs.openstack.org/magnum/→.../magnum/latest/등):code:역할 1곳을 인라인 리터럴로, 수동 번호 목록을#.로 바꿨습니다.도구
tox -e linkcheck환경을 추가하고 CI에continue-on-error단계로 넣었습니다. 깨진 링크와 리다이렉트를 알리되 빌드는 막지 않습니다.intersphinx_mapping = {}과 해당 확장을 제거했습니다. 다시 켜는 방법은 주석으로 남겼습니다.Type of change
Related issue
Fixes #50
Checklist
tox -e docstox -e pep8index.rsttoctree. (새 문서 없음)heading levels,
한글(English)on first use of a term).Additional notes
리뷰 시 봐주셨으면 하는 부분
foundations/kubernetes-csi.rst의 "세부 구조" 절은 표기 수정이 아니라 내용을 고쳤습니다. kubelet 이 CSI 컴포넌트로 적혀 있고 "~를 통해 ~를 통해" 로 문장이 깨져 있어, 컨트롤러 플러그인 / 노드 플러그인 두 종류와 이를 UNIX 소켓으로 호출하는 kubelet 구조로 다시 썼습니다. 원저자 의도와 맞는지 확인이 필요합니다.linkcheck에서netapp.com링크는 봇 접근에만 403 을 돌려주고 사람은 정상적으로 볼 수 있어, 링크를 지우는 대신linkcheck_ignore에 사유와 함께 등록했습니다.검증
tox -e docs(한국어,-W)tox -e docs-en(영어/en/,-W)tox -e pep8(doc8, 61개 파일)tox -e linkcheck