Readthedocs.org: 문서 읽기에서 MkDocs에 대한 비전

• 검색 인덱싱 RTD는 검색을 위한 인덱싱을 위해 json 빌더(0.17에서 제거됨, #4205 참조)를 사용하고 있었습니다. HTML을 크롤링/인덱싱하는 것과는 대조적으로 이것 또는 이와 유사한 것이 있으면 좋을 것입니다.

MkDocs는 여전히 검색 플러그인 의 일부로 콘텐츠가 포함된 모든 페이지를 나열하는 JSON 파일을 제공합니다. 분명히 RTD에는 lunr.js 및 지원 항목이 필요하지 않지만 플러그인은 JSON 데이터만 제공하도록 구성 할 수 있습니다. 즉, 구성은 테마 구성 내에서 정의하기 위한 것이므로 RTD가 사용자 테마 선택을 존중한다면 해당 구성을 재정의하기 어려울 것입니다. 그리고 JSON 데이터는 실제로 전체 페이지가 아닌 헤더 섹션으로 나뉘며 검색 구현과 함께 작동하거나 작동하지 않을 수 있습니다.

그러나 RTD의 목적을 위해 플러그인의 관련 부분 을 복제하는 것은 너무 어렵지 않아야 합니다. 플러그인이 테마에 삽입될 수 있으므로 플러그인을 사용하여 versions.html 템플릿을 재정의하거나 자신의 JavaScript를 추가하거나 필요한 기타 테마 모드를 추가할 수도 있습니다. 다시 말해, 단일 플러그인으로 RTD는 테마 작성자가 제공해야 하는 후크를 문서화하는 한 모든 타사 MkDocs 테마와 쉽게 작동할 수 있다고 생각합니다. 자세한 내용 은 문서 를 참조하세요.

한 가지 까다로운 부분은 플러그인을 구성에 포함시키는 것입니다. 기본적으로 사용자가 정의하지 않은 plugins 설정은 search 플러그인을 포함합니다. 그러나 사용자 정의 플러그인이 포함된 경우 사용자 정의 플러그인만 사용됩니다(추가되지 않음). 따라서 플러그인을 추가할 때 사용자 포함 플러그인을 느슨하게 하지 않도록 주의해야 합니다. 사용자가 명시적으로 search 를 포함하는 경우를 제외하고는 목록에서 해당 항목도 제거해야 합니다.

• 형식 안정성 특히 테마 주변에서 mkdocs.yml 형식의 안정성. 0.15.x에서 1.x로 이전 버전과 호환되지 않는 변경 사항이 꽤 있었습니다. RTD는 여러 버전의 MkDocs를 지원하기 때문에 이것이 문제였습니다. 테마 재정의를 중단하면 문제가 줄어들 수 있습니다.

이해했다. 그러나 이전 버전과 호환되지 않는 변경 사항은 모두 1.0 이전 개발의 일부였습니다. 이제 1.0이 출시되었으므로 1.x 시리즈 전체에서 안정성을 유지할 계획입니다(2.0은 아직 로드맵에 없음). 향후 변경 사항은 기본적으로 추가되어야 하며 기존 구성 형식으로 계속 작동해야 합니다.

MkDocs가 RTD에서 필요로 하는 것

위에 나열된 항목 외에도 다음이 필요합니다.

• RTD가 의존하는 것에 대한 명확한 문서 . 이상적으로는 RTD가 사용하는 모든 후크/API를 나열하는 하나의 위치가 있을 것입니다. 예를 들어, 그러한 목록이 존재한다면 우리는 json 빌더를 제거하지 않았을 수 있습니다. 예, 이 정보는 코드를 읽어서 얻을 수 있지만, 빠른 확인이 필요할 때마다 실용적이지는 않습니다. 요청된 문서는 최종 사용자를 위한 것이 아니라 MkDocs 개발자, 테마 개발자 및 플러그인 개발자를 위한 것입니다. 공개 문서에 맞지 않을 수 있으므로 Wiki 페이지 등이 좋습니다.

이 문제는 최근 활동이 없었기 때문에 자동으로 오래된 것으로 표시되었습니다. 더 이상 활동이 없으면 폐쇄됩니다. 귀하의 기여에 감사드립니다.

@waylan 감사합니다 답변이 너무 늦어서 죄송합니다. 우리는 이제 RTD에서 MkDocs 경험을 개선하는 데 집중하고 있으며 search/search_index.json 파일에서 검색 데이터를 인덱싱할 것입니다. 따라서 변경 사항이 있는 경우 해당 파일의 구조에 대한 변경 사항이 생략되거나 버전이 지정되면 좋을 것입니다. 나는 당신이 언급한 문서를 다음 일/주에 작성할 것입니다.