Readthedocs.org: Visión para MkDocs en Read the Docs

• Indexación de búsqueda RTD estaba usando el constructor json (eliminado en 0.17, consulte #4205) para indexar para la búsqueda. Sería bueno tener esto o algo parecido en lugar de rastrear/indexar el HTML.

MkDocs todavía proporciona un archivo JSON que enumera todas las páginas con su contenido como parte del complemento de búsqueda . Obviamente, RTD no necesita lunr.js y elementos de soporte, pero el complemento se puede configurar para proporcionar solo los datos JSON. Dicho esto, la configuración está destinada a definirse desde dentro de la configuración de un tema, por lo que si RTD respeta las opciones de tema de los usuarios, sería difícil anular esa configuración. Y los datos JSON en realidad se dividen en secciones de encabezado, no en páginas completas, que pueden o no funcionar con su implementación de búsqueda.

Sin embargo, no debería ser demasiado difícil clonar las partes relevantes del complemento para el propósito de RTD. Como los complementos se pueden inyectar en los temas, incluso puede usar su complemento para anular la plantilla versions.html , o para agregar su propio JavaScript, o cualquier otra modificación de tema que pueda necesitar. En otras palabras, creo que, con un solo complemento, RTD podría funcionar fácilmente con cualquier tema de MkDocs de terceros, siempre que documente los ganchos que los autores del tema deben proporcionar. Vea los documentos para más detalles.

La única parte complicada es incluir su complemento en la configuración. De forma predeterminada, una configuración no definida (por el usuario) plugins da como resultado que se incluya el complemento search . Sin embargo, si se incluyen complementos definidos por el usuario, solo se utilizan los complementos definidos por el usuario (no es aditivo). Por lo tanto, debe tener cuidado de no perder los complementos incluidos por el usuario al agregar su complemento. Excepto que si el usuario incluyó explícitamente search , también deberá eliminarlo de la lista.

• Estabilidad de formato Estabilidad en el formato mkdocs.yml, especialmente en torno a temas. Hubo bastantes cambios incompatibles con versiones anteriores aquí de 0.15.x a 1.x. Debido a que RTD admite varias versiones de MkDocs, esto era un problema. Esto puede ser un problema menor una vez que dejemos de anular el tema.

Entendido. Sin embargo, esos cambios incompatibles con versiones anteriores fueron parte del desarrollo anterior a 1.0. Ahora que se lanzó 1.0, tenemos la intención de mantener la estabilidad en toda la serie 1.x (2.0 aún no está en nuestra hoja de ruta). Los cambios futuros deben ser principalmente aditivos y continuar trabajando con el formato de configuración existente.

Cosas que MkDocs necesita de RTD

Además del artículo mencionado anteriormente, también necesitamos:

• Documentación clara de lo que depende de RTD . Idealmente, habría una ubicación que enumeraría todos los ganchos/API que usa RTD. Por ejemplo, si existiera tal lista, es posible que no hayamos eliminado el generador json , ya que teníamos la impresión de que no se usaba. Sí, esta información está disponible leyendo el código, pero eso no es práctico cada vez que necesitamos hacer una verificación rápida. Tenga en cuenta que la documentación solicitada no es para usuarios finales, sino para desarrolladores de MkDocs, desarrolladores de temas y posiblemente desarrolladores de complementos. Es posible que no encaje en su documentación pública, por lo que una página wiki o similar estaría bien.

Este problema se ha marcado automáticamente como obsoleto porque no ha tenido actividad reciente. Se cerrará si no se produce más actividad. Gracias por sus aportaciones.

@waylan gracias, perdón por la respuesta tan tardía. Ahora nos estamos enfocando en mejorar la experiencia de MkDocs en RTD, vamos a indexar los datos de búsqueda del archivo search/search_index.json . Por lo tanto, sería bueno si cualquier cambio en la estructura de ese archivo se eliminara o versionara si hay cambios. Estaré escribiendo el documento que mencionas en los próximos días/semanas.