Upgrade to Pro — share decks privately, control downloads, hide ads and more …

JConf Peru 2023 - Documenta tu Java App usando ...

JConf Peru 2023 - Documenta tu Java App usando Sphinx

Documenta tus aplicaciones Java usando Sphinx reStructuredText markup y manten tu documentación actualizada.

Carlos Zela Bueno

December 04, 2023
Tweet

More Decks by Carlos Zela Bueno

Other Decks in Programming

Transcript

  1. Agenda • Que es Sphinx? • Demo Sphinx • Demo

    Uso Java • Demo Uso Java Maven
  2. Que es Sphinx • Sphinx es un software generador de

    documentación que convierte fi cheros reStructuredText (lenguaje de marcas) en sitios web HTML y otros formatos, incluyendo PDF, EPub y man. Saca provecho de la naturaleza extensible de reStructuredText y sus extensiones (ej. para generar automáticamente documentación desde código fuente, escribir notación matemática o resalzar código).
  3. Git - 0 • $ clonar repositorio: https://github.com/davisusanibar/jconf-sphinx • $

    git branch • main • sphinx-documentacion • sphinx-documentacion-texto • sphinx-documentacion-texto-codigo • sphinx-documentacion-texto-codigo-validacion • sphinx-documentacion-texto-codigo-validacion-extension-custom • sphinx-documentacion-texto-codigo-validacion-extension-custom-maven • sphinx-java-options • $ git checkout sphinx-documentacion
  4. • Instalar Sphinx • $ pip install -U sphinx •

    Para generar el esqueleto base de Sphinx debemos usar su interactive tool llamado sphinx-quickstart • $ sphinx-quickstart Sphinx en VM
  5. Sphinx en Docker • Crear directorio para el volumen docker

    que rapeara la estructura de archivos del proyecto Sphinx con el host: • $ mkdir jconf • Generamos el esqueleto base de Sphinx con: • $ docker run -it --rm -v ./jconf:/docs sphinxdoc/sphinx sphinx- quickstart • $ tree jconf
  6. Lab - 0 - Lo que viene de caja •

    VM • $ pip install -U sphinx • $ mkdir jconf-lab0 • $ cd jconf-lab0 • $ sphinx-quickstart • $ make html • Docker • $ mkdir jconf-lab0 • $ docker run -it --rm -v ./jconf-lab0:/docs sphinxdoc/sphinx sphinx-quickstart • $ docker run -it --rm -v ./jconf-lab0:/docs sphinxdoc/sphinx make html
  7. Documentación Texto • Abrimos el proyecto creado por el interactive

    tool en nuestro IDE favorito. • Generamos nuestra documentación en el archivo “jconf/source/index.rst” • Una vez terminada nuestra documentación lo compilamos al formato que necesitemos html, latex, ePub, otros.
  8. Documentación Texto # * = - ^ “ .. code-block::

    python import … Cabeceras / Títulos Bloques de Código Links y Referencias Mi Titulo ======= Mayor detalle en `Guia de Sphinx`_ con ejemplos reales. … _`Guia de Sphinx`: https://demo.com https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html https://sphinx-intro-tutorial.readthedocs.io/en/latest/rst_intro.html
  9. Lab - 1 - Documentación Texto • VM • $

    pip install -U sphinx • $ mkdir jconf-lab1 • $ cd jconf-lab1 • $ sphinx-quickstart • Agregar texto al documento: ./jconf-lab1/source/index.rst • $ make html • Docker • $ mkdir jconf-lab1 • $ docker run -it --rm -v ./jconf-lab1:/docs sphinxdoc/sphinx sphinx-quickstart • Agregar texto al documento: ./jconf-lab1/source/index.rst • $ docker run -it --rm -v ./jconf-lab1:/docs sphinxdoc/sphinx make html
  10. Lab - 2 - Documentación Código • VM • $

    pip install -U sphinx • $ mkdir jconf-lab2 • $ cd jconf-lab2 • $ sphinx-quickstart • Agregar código al documento (usando la directiva: code-block): ./jconf-lab2/source/index.rst • $ make html • Docker • $ mkdir jconf-lab2 • $ docker run -it --rm -v ./jconf-lab2:/docs sphinxdoc/sphinx sphinx-quickstart • Agregar código al documento (usando la directiva: code-block): ./jconf-lab2/source/index.rst • $ docker run -it --rm -v ./jconf-lab2:/docs sphinxdoc/sphinx make html
  11. Documentación Validación Código • Sphinx cuenta con una variedad de

    “extensiones” para poder extender la funcionalidad de la aplicación. • Estas extensiones se registran en el archivo “conf.py”
  12. Documentación Validación Código extensions = [ 'sphinx.ext.doctest', ] conf.py Este

    es un ejemplo que declara su código a ejecutar usando la directiva ``testcode`` y valida la salida del programa con lo que se declara en la directiva ``testoutput``. .. testcode:: print('JConf Python') .. testoutput:: JConf Python Resultado Validación $ make html $ make doctest
  13. Lab - 3 - Documentación Validación Código • VM •

    $ pip install -U sphinx • $ mkdir jconf-lab3 • $ cd jconf-lab3 • $ sphinx-quickstart • Agregar código al documento (usando la directiva: testcode): ./jconf-lab3/source/index.rst • Agregar extension al archivo de con fi guración ./jconf-lab3/source/conf.py: sphinx.ext.doctest • $ make html • $ make doctest • Docker • $ mkdir jconf-lab3 • $ docker run -it --rm -v ./jconf-lab3:/docs sphinxdoc/sphinx sphinx-quickstart • Agregar código al documento (usando la directiva: testcode): ./jconf-lab3/source/index.rst • Agregar extension al archivo de con fi guración ./jconf-lab3/source/conf.py: sphinx.ext.doctest • $ docker run -it --rm -v ./jconf-lab3:/docs sphinxdoc/sphinx make doctest • $ docker run -it --rm -v ./jconf-lab3:/docs sphinxdoc/sphinx make html
  14. Documentación Validación Código con Extension Custom • Sphinx ofrece con

    fi guraciones para prender cosas que podrías necesitar y apagar otras no necesarias. • En el siguiente ejemplo vamos a ver como cargar una extension que nos permita documentar y validar nuestro código Java usando Sphinx.
  15. Documentación Validación Código con Extension Custom conf.py Resultado Validación $

    make html $ make javadoctest import os import sys sys.path.append( os.path.abspath("../ext")) extensions = [ "javadoctest" ] ext/javadoctest.py app.add_directive('javatestsetup', JavaTestsetupDirective) app.add_directive('javatestcleanup', JavaTestcleanupDirective) app.add_directive('javadoctest', JavaDoctestDirective) app.add_directive('javatestcode', JavaTestcodeDirective) app.add_directive('javatestoutput', JavaTestoutputDirective) ( Nueva Directivas Para Java )
  16. Lab - 4 - Documentación Validación Código con Extension Custom

    • Docker • $ mkdir jconf-lab4 • $ cd jconf-lab4 • $ cat Docker fi le # Sphinx + Java/Maven Support FROM sphinxdoc/sphinx WORKDIR /docs RUN apt-get update && apt-get -y install maven openjdk-17-jdk
  17. Lab - 4 - Documentación Validación Código con Extension Custom

    • Docker (cont) • $ docker build . -t sphinx-jconf:v1 • Agregar código al documento (usando la directiva: javatestcode): ./jconf-lab4/source/index.rst • Crear el archivo ./jconf-lab4/ext/javadoctest.py con las directivas creadas en https://gist.github.com/ davisusanibar/1ad47ec8a12d91e311558ab01f912f26 • Agregar la nueva extension al archivo de con fi guración ./jconf-lab4/source/conf.py: javadoctest • $ cd .. • $ docker run -it --rm -v ./jconf-lab4:/docs sphinx-jconf:v1 make javadoctest • $ docker run -it --rm -v ./jconf-lab4:/docs sphinx-jconf:v1 make html
  18. Documentación Validación Código con Extension Custom Maven • La nueva

    extension customizada javadoctest.py también ofrece soporte para proyectos que manejan dependencias de tercero via un gestor de dependencias por ejemplo maven. • En el siguiente ejemplo vamos a ver como cargar una extension que nos permita documentar y validar nuestro código Java usando Sphinx usando un gestor de dependencias Maven.
  19. Documentación Validación Código con Extension Custom Maven conf.py Resultado Validación

    $ make html $ make javadoctest ext/javadoctest.py app.add_directive('javatestsetup', JavaTestsetupDirective) app.add_directive('javatestcleanup', JavaTestcleanupDirective) app.add_directive('javadoctest', JavaDoctestDirective) app.add_directive('javatestcode', JavaTestcodeDirective) app.add_directive('javatestoutput', JavaTestoutputDirective) ( Nueva Directivas Para Java ) import os import sys import pathlib sys.path.append( os.path.abspath("../ext")) extensions = [ "javadoctest" ] javadoctest_config = { 'flavor': 'java_with_maven', 'path': pathlib.Path(__file__).parent / 'example', }
  20. Lab - 5 - Documentación Validación Código con Extension Custom

    Maven • Docker • $ mkdir jconf-lab5 • $ cd jconf-lab5 • $ cat Docker fi le # Sphinx + Java/Maven Support FROM sphinxdoc/sphinx WORKDIR /docs RUN apt-get update && apt-get -y install maven openjdk-17-jdk
  21. Lab - 5 - Documentación Validación Código con Extension Custom

    • Docker (cont) • $ docker build . -t sphinx-jconf:v1 • Agregar código al documento (usando la directiva: javatestcode): ./jconf-lab5/source/index.rst • Crear el archivo ./jconf-lab5/ext/javadoctest.py con las directivas creadas en https://gist.github.com/davisusanibar/1ad47ec8a12d91e311558ab01f912f26 • Agregar la nueva extension al archivo de con fi guración ./jconf-lab5/source/conf.py: javadoctest • De fi nir que se usara un proyecto Maven y especi fi carle la ruta del proyecto example/pom.xml:} javadoctest_con fi g = { ' fl avor': ‘java_with_maven', 'path': pathlib.Path(__ fi le__).parent / 'example', } • $ cd .. • $ docker run -it --rm -v ./jconf-lab5:/docs sphinx-jconf:v1 make javadoctest • $ docker run -it --rm -v ./jconf-lab5:/docs sphinx-jconf:v1 make html
  22. Referencias • Sphinx project - https://github.com/sphinx-doc/sphinx • Como añadir tu

    propia extension de Sphinx - https://sphinx-intro-tutorial.readthedocs.io/en/ latest/sphinx_extensions.html • Nuevas Directivas Java Sphinx - https://gist.github.com/davisusanibar/ 1ad47ec8a12d91e311558ab01f912f26 • Ejemplos Java usando la nueva Directiva - https://github.com/sphinx-doc/sphinx/blob/ 1a3af3ca4d2e509039bf164f15d98f0f4992f60b/tests/roots/test-ext-javadoctest/javadoctest.rst • Sphinx PR relacionado para agregar nueva Java directiva al Core de Sphinx - https://github.com/ sphinx-doc/sphinx/pull/11305 • GH Project Demo - https://github.com/davisusanibar/jconf-sphinx (checkout a ramas de acuerdo al nivel a revisar)