Creando Documentación con Sphinx

Santos Gallegos - [email protected]
@stsewd

¿Quién soy?

Feature que no está documentado no existe

Importancia de escribir documentación

  • Transmitir conocimiento de manera rápida y fácil
  • Aprender cómo instalar, usar y configurar el software
  • Aprender qué opciones provee el software
  • Aprender qué interfaces provee el software
  • Aprender cómo luce el software antes de instalarlo
  • Aprender cómo no usar el software

Importancia de documentación en proyectos open source

  • Más usuarios usarán tu proyecto
  • Tendrás colaboradores
  • Menos preguntas que responder
  • Y una comunidad más grande

Importancia de leer documentación

Probablemente...

  • Lo que te estás preguntando está en la documentación
  • El problema que estás teniendo está en la documentación
  • La mejor manera de hacer lo que estás pensando está en la documentación

... ¡Y probablemente está en la sección que te saltaste!

¿Por qué no leen tu documentación?

  • Difícil de encontrar y leer
  • Difícil de entender
  • Incompleta
  • No está en su idioma nativo

Sphinx

https://www.sphinx-doc.org/

pip install sphinx

  • reStructuredText
  • ¡Cross-references!
  • Documentación en prosa y docstrings
  • Extensible
  • HTML, PDF, ePub
  • Temas
  • Multi-lenguaje
  • Python, requests, Flask, Django, Linux kernel

Markdown

  • Sintaxis más fácil de aprender
  • Markdown no tiene un estándar
  • Markdown no es extensible

reStructuredText

www.sphinx-doc.org/en/master/usage/restructuredtext/
  • Estándar
  • Extensible
  • Roles & directives

Primer proyecto en sphinx

sphinx-quickstart docs

          
docs
├── _build
├── conf.py
├── index.rst
├── make.bat
├── Makefile
├── _static
└── _templates
          
          

Walktrough con los docs de flask

          
git clone --depth=1 https://github.com/pallets/flask/
cd flask
pip install -e .
pip install -r docs/requirements.txt
cd docs
make html
          
          

Extensiones

www.sphinx-doc.org/en/master/usage/extensions/
  • intersphinx
  • autodoc
  • autosectionlabel

Tools recomendadas

Alternativas

  • Mkdocs
  • Doxigen
  • Rustdoc
  • JSDoc

¡Documenta tu siguiente proyecto con Sphinx!