오픈 소스 프로젝트의 문서를 관리하는 방법은 무엇입니까? [닫은]

나는 점점 커지는 오픈 소스 프로젝트의 창시자입니다. 현재 문서를 관리하는 가장 좋은 방법을 찾으려고 노력하고 있습니다. 내가 고려한 옵션은 다음과 같습니다.

• HTML 웹 사이트
• Github Wiki
• Github에서 호스팅되는 마크 다운 파일
• Github README.md에 모든 문서 배치

이 문서는 이미 Markdown으로 작성되었으며 사용 가능한 방법을 알 수 없습니다. 소스를 브랜치하고 태그를 지정할 수있는 것처럼 문서를 브랜치하고 태그를 지정할 수 있기 때문에 실제로 Git을 사용하고 있습니다.

Markdown 라이브러리를 사용하여 Markdown을 HTML로 번역하고 스타일이 지정된 웹 사이트에 표시 할 수 있습니다. 변경 사항이있을 때마다 웹 사이트에 변경 사항을 업로드해야하며 설명서의 다른 "태그"를 모두 관리하기가 어려울 수 있습니다.

Github Wikis (내가 아는 한)는 현재 지점에 따라 변경되지 않습니다. 따라서 언제든지 Github Wiki 형식의 "마스터"버전의 문서 만 가질 수있었습니다.

Github README에 모두 넣는 것은 다소 깔끔합니다. 분기 및 태깅이 가능하지만 사용하기에 약간 지 치며 쉬운 탐색에 적합하지 않습니다.

멋진 해결책이 없습니까? 다른 옵션이 있습니까?

내가 말하고자하는 한 가지는 문서가 소스 코드 파일에 있어야하며 (원하는 마크 업을 사용하여) 문서에서 자동으로 생성 된 문서입니다.
최소한 사이트에서 소스 패키지의 일부로 문서의 형식화 된 다운로드를 생성 할 수 있으므로 사용자는 특정 문서 도구가 필요하지 않습니다

다른 사람이 기능을 수정 / 추가 한 다음 동일한 파일에 바로 인접한 약간의 마크 업 문서를 편집 / 추가 할 가능성은 낮을 수 있지만 다른 문서 저장소에서 완전히 다른 파일을 찾아서 동일한 작업을 수행 할 가능성은 약간 있습니다 0보다 작습니다.

원하는 경우 언제든지 큰 텍스트 블록을 포함하는 tutorial.h를 가질 수 있지만 소스의 일부로 취급하십시오.

프로젝트가 라이브러리 인 경우 코드 자체의 주석에서 API 구문을 문서화하기 위해 javadoc 스타일 문서를 능가하는 것은 없습니다.

튜토리얼, 사용 예제 등에 관한 문서는 위키 형식을 사용하는 것이 좋습니다. 내가 본 다른 프로젝트에는 다른 브랜치마다 별도의 페이지가 있습니다. 새 브랜치를 시작하면 새 페이지로 변경되지 않은 것을 복사하고 거기서 업데이트합니다.

위키를 추천하는 이유는 일화이지만 개인적인 경험 때문입니다. 여러 차례 오픈 소스 프로젝트에 대한 문서 업데이트를 제공했지만 모두 위키에있었습니다. 내가 무언가를 알아 내려고 노력하고 문서가 잘못되거나 도움이되지 않는다면, 그것을 알아 낸 후에 나는 문서에있는 동안 위키를 업데이트하고 마음에 새롭습니다. 갚을 수없는 느낌이 들지 않는다면 적어도 1 년에서 2 년 안에 다시 찾아 볼 필요가 있다는 것을 알고 있기 때문입니다.

위키가 없다면, 문서를 생성하는 방법, 저장 위치, 소스 제어에서 최신 정보를 얻는 방법, 편집하는 방법, 실제 편집하는 것, 그리고 입력하는 것 사이에 진입 장벽이 너무 귀찮습니다. 메일 링리스트를 탐색하여 패치를 수락합니다.

문서를 엄격하게 제어하려면 항상 가장 편한 것을 사용하십시오. 대부분 문서를 업데이트하는 사람이기 때문입니다. 커뮤니티 참여를 장려하려면 위키를 사용하십시오.

소스와 함께 호스팅되는 마크 다운 파일은 매우 잘 작동합니다.

예를 들어 RST 기반 docutils 도구는 한 문서 세트에서 HTML 또는 LaTex (및 PDF)를 작성할 수 있습니다.

이것은 실제로 옵션 1과 옵션 3을 결합한 것입니다.

문서를 Markdown에서 reStructuredText로 변환하는 것이 마음에 들지 않으면 Sphinx를 고려하십시오 . 마크 다운만큼이나 쉽지만 훨씬 강력합니다.