Readthedocs.org: MkDocs 빌드: MkDocs 고유 테마 사용 허용

현재 테마는 하드 코딩되어 있습니다. https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/mkdocs.py#L147

:+1:

주된 이유는 기본 mkdocs 테마에 정의된 블록이 없기 때문입니다. 즉, 템플릿을 재정의할 수 없습니다. 이로 인해 RTD 기능을 맨 위에 제공할 수 있는 일부 페이지 수준 컨텍스트를 삽입하기가 어렵습니다. RTD에서 실제로 지원하기 전에 업스트림 mkdocs에 들어가야 하는 것입니다.

그동안 mkdocs 사용할 때 사용자 정의 테마가 현재 지원되지 않는다는 FAQ를 추가하는 것이 좋을 것 같습니다(예: 이 질문 뒤에). https://docs.readthedocs.org/en/latest/theme.html에 메모를 추가하는 것도 좋습니다. 맨 위에 있는 현재 메모는 그것이 무엇을 언급하는지에 대해 약간 모호합니다.

이 문제를 발견할 때까지 사용자 지정 테마가 지원되지 않는다는 것이 분명하지 않았습니다.

@cjerdonek에 동의: 로컬에서 구축한 mkdocs 웹사이트가 내가 원하는 테마를 사용하고 RTD의 버전이 이를 반영하지 않았다는 사실에 놀랐습니다. _major_ 문제는 아니지만 구현될 수 있거나 메모가 어딘가에 작성된다면 환상적일 것입니다. 감사 해요 !

저에게도 같은 문제입니다. 아직 문서화되지 않았습니다.

여기에 메모를 추가하는 것이 가장 합리적일 것입니다. https://github.com/rtfd/readthedocs.org/blob/master/docs/getting_started.rst

AFAICT, 이것은 MkDocs를 다루는 문서의 유일한 부분입니다.

:+1:

주된 이유는 기본 mkdocs 테마에 정의된 블록이 없기 때문입니다. 즉, 템플릿을 재정의할 수 없습니다. 이로 인해 RTD 기능을 맨 위에 제공할 수 있는 일부 페이지 수준 컨텍스트를 삽입하기가 어렵습니다. RTD에서 실제로 지원하기 전에 업스트림 mkdocs에 들어가야 하는 것입니다.

@ericholscher 어떤 블록이 필요합니까? 우리가 이것을 어딘가에, 어떻게든 정의할 수 있다면 좋을 것입니다. 그러면 MkDocs가 이를 준수하는지 확인하게 되어 기쁩니다.

내가 말할 수 있는 바에 따르면 필요한 블록은 검색 통합과 버전 전환 장치뿐입니다.

확실히 여기에서 약간의 진전을 보고 싶습니다. MkDocs 테마가 더 이상 http://mkdocs.github.io/mkdocs-bootswatch/의 일부로만 제공되면 상황이 훨씬 더 복잡해집니다.

별로, 내가 생각하지 않는 것을 복잡하게 만들지 않을 것입니다.

그것은 내가 생각하지 않는 것을 복잡하게 만들지 않을 것입니다

이 문제를 OT로 받아들이고 싶지는 않지만 RTD가 MkDocs 외에 인프라에서 mkdocs-bootswatch를 사용할 수 있도록 해야 하지 않을까요?

사용자는 RTD로 원하는 임의의 Python 패키지를 지정할 수 있습니다. 이것이 MkDocs 지원 테마만 허용한다면 노력할 가치가 없을 것입니다 :)

죄송합니다. 하지만 이 문제의 상태에 대해 약간 불분명합니다. MkDocs 측에서 여전히 작업이 필요합니까(앞서 언급한 블록을 정의하기 위해), 아니면 RTD의 MkDocs 빌더가 mkdocs.yml 지정된 테마를 확인하도록 하고 있는 경우 사용하도록 "그냥" 해야 합니까?

@tatablack 나는 RTD 측에서 작업이 필요하다고 생각합니다. MkDocs가 RTD의 기대와 일치하지 않으면 잘 통합되지 않을 수 있는 것이 사실입니다(그러나 이것은 사용자 지정 Sphinx 테마에서도 마찬가지입니다).

RTD의 MkDocs 빌더가 mkdocs.yml에 지정된 테마를 확인하고 있는 경우 사용하도록 해야 합니까?

실제로는 그보다 더 간단합니다. 현재 RTD는 사용자가 지정한 테마를 덮어씁니다. 다른 테마를 활성화하려면 RTD가 이 설정 덮어쓰기를 중지하기만 하면 됩니다.

@d0ugal 감사합니다. 방금 PR(단순한 솔루션 포함)을 열었습니다. 어떻게 진행되는지 보겠습니다.

사용자 정의 테마를 지원할 수 있는 RTD의 상태는 무엇입니까? 문서 플라이아웃과 같은 RTD 기능이 사용자 정의 테마에 구현됩니까?

그대로, 우리는 RTD의 mkdocs 프로젝트에 사용자 정의 테마를 허용하는 것에 반대합니다. 문서에 RTD를 추가하지 않으면 사용자 경험이 저하되며 사용자 정의 테마를 허용하는 것은 응집력 있는 사용자 경험에 대한 우리의 노력을 더욱 희석시킬 뿐입니다.

Sphinx의 사용자 지정 테마가 동일한 효과, 즉 사용자 경험 저하로 이어진다는 데 동의합니다. 저는 오히려 프로젝트 전반에 걸친 문서화에 대한 공통 인터페이스를 선호합니다. 적어도 Sphinx를 사용하면 템플릿 프로세스의 일부를 제어하여 모든 테마에 주입할 수 있습니다.

@agjohnson , 나는 당신이 PR #2188 ( Needed: design decision )에 붙인 레이블에 동의하므로 사용자 정의 테마에 찬성하여 주장하고 싶습니다.

1. 특정 기능의 (잠재적인) 손실이 잘 문서화되어 있는 한, 정보에 입각한 결정을 내리고 청중을 위한 사용자 정의 테마의 이점을 평가하고 특정 RTD를 제공하지 않는 단점과 비교하는 것은 문서 작성자에게 달려 있습니다. 독자가 다른 RTD 문서 세트에서 익숙할 수 있는 기능.
2. 사용자 정의 테마를 선택하는 것이 가능하거나 더 쉬우면 그 중 일부가 더 인기를 _수도 있고_ 더 많이 사용되며, 이는 원래 작성자나 커뮤니티에서 테마를 사용하는 사람이 테마 자체를 개선할 _수도 있습니다. 나는 이것이 가설이라는 것을 알고 있지만 확실히 테마를 사용할 수 없다면 그것을 개선해야 할 필요성을 느끼지 않을 것입니다.
3. 스핑크스 대 MkDocs. 이 스레드에서 내가 이해하는 것은 RTD와 MkDocs 간의 통합 수준이 Sphinx와 동일하지 않다는 것입니다(당신이 언급했듯이 "템플릿 프로세스의 일부를 제어할 수 있음"). 그러나 (그리고 이것은 이 스레드의 주제와 다를 수 있습니다. 그렇다면 언제든지 저를 닥치십시오.) 어떤 후크가 누락되었는지 정확히 찾을 수 없었습니다. @d0ugal : MkDocs 측에서 어떤 개선 사항이 있는지 알고 있습니까? 그렇다면 가능합니까?

조금 이상한 문제 - 약 2년이지만 RTD 테마가 되기 위한 요구 사항이 무엇인지 제대로 이해하지 못한다고 생각합니다. 사용자 지정 Sphinx 테마와 동일하게 하려면 MkDocs 테마에 무엇이 있어야 합니까?

사용자 정의 테마를 아예 종료하기로 결정했다면 - OK. 그러나 허용되는 동안 Sphinx 작성자와 비교하여 MarkDown 작성자를 이러한 방식으로 제한할 이유가 없는 것처럼 보입니다.

¿이 문제의 상태는 무엇입니까?
내 말은, 수정되지 않거나 mkdocs 테마를 RTD와 호환되도록 만들 수 있습니까?

#2188에서 언급했듯이 -- 거기에 나열된 이유 때문에 우리는 이것을 지원하지 않기로 결정했습니다.