readthedocs.org에서 MkDocs와 함께 외부 테마를 사용할 수 있습니까?

Question

필자는 포함 된 ReadtheDocs 테마에서 내 프로젝트의 Bootswatch United 테마로 전환했습니다. 이 테마로 pip install mkdocs-bootswatch을 작성하고 theme: readthedocs을 파일의 theme: united으로 변경했습니다.

그러나 프로젝트가 Read the Docs에서 성공적으로 빌드되었지만 문서는 표준 readthedocs 테마를 유지합니다. 로컬로 (mkdocs serve을 사용하여) 실행하면 United 테마와 함께 올바르게 나타납니다.

어딘가에 조정해야하는 코드가 있습니까? 추가해야하는 요구 사항 파일은 무엇입니까? ReadtheDocs에 외부 테마를 올바르게 표시하려면 어떻게해야합니까? 아니면 실제로 readthedocs.org에서 외부 테마를 사용할 수 있습니까?

참고 : 나는 MkDocs 직원에게 물어 보았고 ReadTheDocs 제한이라고 말했으므로 수행해야 할 것이 있으면 ReadTheDocs 관련 솔루션처럼 보입니다. 그렇지 않으면 GitHub 페이지 나 비슷한 것으로 전환해야 할 수도 있습니다.

Answer 1

ReadtheDocs source code을 보았습니다. 실제로 설정 구성을 덮어 쓰고 자신의 템플릿을 강제 실행하는 것처럼 보입니다. ReadtheDocs에 대한 JavaScript 및 탐색 기능을 페이지에 삽입하고 알려진 테마를 사용하여 주입이 올바르게 수행되었는지 확인할 수 있기 때문에이 작업을 이해합니다. 즉, readthedocs 테마와 동일한 HTML을 사용할 수 없지만 페이지의 모양/스타일을 변경하는 다른 CSS를 사용할 수없는 기술적 인 이유가 없어야합니다. ReadtheDocs가이를 명시 적으로 지원하지 않는 것으로 보입니다.

그런데 템플릿 대체는 if 'theme_dir' not in user_config and self.use_theme에서만 발생합니다. 그러면 오버라이드를 피할 수있는 두 가지 경로가 제공됩니다. 주입 된 물건이 올바르게 작동하여 조심스럽게 움직일 것이라는 보장이 없을 것입니다.

1. theme_dir는 Mkdocs setting이다. 별도의 Python 라이브러리로 MkDocs 테마를 설치하는 대신 테마 파일을 docs_dir 옆의 디렉토리에 복사 한 다음 theme_dir 설정을 가리킬 수 있습니다. MkDocs가 theme_dir 만 사용하도록 theme: null을 설정하십시오.

   아마도 덜 공격적인 접근 방식으로 theme: readthedocs을 설정 한 다음 theme_dir을 사용하여 내장 된 readthedocs 테마에서 제공 한 CSS를 덮어 쓰거나 바꿀 자체 CSS 파일 만 제공 할 수 있습니다. 이것은 ReadtheDocs 주사를 적대적으로 받아들이고 좋아하는 모습을 보여 주어야합니다. 그러나 기존 테마의 HTML로 제한되어 있으므로 자신 만의 CSS를 작성해야하므로 (빌드 된 테마를 사용하지 않아도 됨) 더 많은 작업이 필요할 수 있습니다.

   그 이유는 원하는 테마로 theme을 설정하고 theme_dir을 빈 디렉토리로 지정할 수 있습니다. ReadtheDocs는 theme_dir이 설정되어 있는지 확인하고 디렉토리에 실제로 존재하는 것을 신경 쓰지 않는 것처럼 보입니다.

   참고 : 나는 이러한 제안을 테스트하지 않았으므로 작동하지 않을 수도 있습니다. YMMV.

   이외에도이 모든 기능 (theme과 theme_dir 설정 간의 상호 작용)에 대한 MkdDocs 설명서는 현재 부족합니다. 그러나 일부 최신 additions은 MkDocs (0.16)의 다음 버전이 출시 될 때 생방송이됩니다.

2. use_theme은 readthedocs 및 hardcoded 내부적으로 나타납니다. 내 생각 엔이 사용자가 재정의 할 수 없다는 것입니다. 이 옵션이 제공하는 옵션이 무엇인지 결정하기 위해 코드를 자세히 조사해야합니다.