Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

DocsV3: Update plugin docgen tooling to work with new MD files and structure

Abierto
  • ¿Algo no está bien?
#110 5 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Error
Claridad
Necesita aclaración
Estado de actividad
Estancado
Stack tecnológico
github-actions, ruby
Área
build-system, documentation, tooling

Línea de trabajo

Comienza con plugindocs.rb y la GitHub Action reference_docs.yml; después, compara cómo se generan los documentos de los plugins para las ramas main/9.x y 8.x o anteriores. Revisa los workarounds enlazados y los issues relacionados para conocer el comportamiento actual. Se considera terminado cuando las herramientas generan los documentos de los plugins para las nuevas ramas basadas en MD, preservando al mismo tiempo una compatibilidad equivalente con las ramas ASCIIDOC antiguas.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

LSR

Current stack-versioned plugin docs tooling generates plugin docs for inclusion in the Logstash Reference (LSR). I broke plugin doc generation (for main and 9.0) when I replaced asciidoc source files in the logstash repo with the new MD source files. Tooling is looking for logstash/docs/index.asciidoc, but it's no longer there.

Line 1574 Can't find --doc /home/runner/work/logstash-docs/logstash-docs/logstash/docs/index.asciidoc

Update:
We have work-arounds that let us generate plugin docs PRs after:

Decisions
  • Where should conversion happen? Source? Enrichment? End-of-pipeline?
  • When to migrate source content?
  • We'll likely need a phased approach (short-term, mid-term, long-term) to deal with complexity and volume. What does that look like?
Considerations
  • Need ability to support both MD (for 9.0+) and ASCIIDOC (for 8.x and earlier).
  • File location and Include path settings are different for 9.0+ and 8.x.
  • Link format varies between ADOC and MD, and so far, has required manual cleanup
Tooling affected
Related and relevant
Requirements
  • Stack-versioned docs tooling should be modified to generate plugin docs for main 9.0, and 9.x branches
  • Stack-versioned docs tooling should maintain existing (or equivalent) functionality to build plugin docs for 8.x series and earlier branches.
Lenguaje dominante
Ruby
Estrellas
4
Forks
12
Sin PR fusionados en 30 d

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de elastic/docs-tools

Todos los issues de elastic/docs-tools

Issues similares

Más issues de Ruby

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.