Tech Talk CodiLime 28.02.2018 Michał Sochoń - Sphinx, reST & Ansible You can find the recording here: https://youtu.be/F60O_KkUsZg

1. Sphinx, reST i Ansible
Wprowadzenie do automatycznego generowania dokumentacji

2. Info
● Na SlideShare dostępne są notatki
pod oknem prezentacji w zakładce Notes
● Prezentacja na SlideShare zawiera więcej
slajdów niż materiał wideo.

3. Agenda
● O czym jest ta prezentacja
● O czym NIE jest ta prezentacja
● Problemy i Skutki
● Jak można to naprawić
● Co dostajemy w efekcie
● Przykład z Ansible

4. O czym jest ta prezentacja
● Jaki jest ogólny problem?
● Jakim sposobem możemy to rozwiązać
● Co dostaniemy w zamian
● W jakim kierunku można to pociągnąć

5. O czym NIE jest ta prezentacja
● Jaki pisać dobrą dokumentację
● Przegląd innych rozwiązań
● Niestety nie mam komend dla Windows
● reStructuredText specjalnie zdawkowo opisany

6. Problem
● Nie chce mi się
● Brak czasu
● Permanentna zmiana
● Nie wiemy jak

7. Skutki
● O tamten w rogu wie...
● Chcą dokumentację teraz?
● Mam kogoś szkolić?
● Fajnie, że mamy internet
● FFFFFFFFFFF…..

8. Jak to naprawić?
Napisać dokumentację.

10. Po co?
● Oszczędność czasu zespołu
● Logiczny podział wiedzy
● Różne scenariusze pracy
● Integracje

11. Jak to zrobić?
● Przejrzeć to co jest i dopisać
● Najlepiej trzymać w repo projektu
● Automatycznie generować i publikować
● Używać perswazji :)

12. Przejrzenie tego co jest
● Istniejące dokumenty
● W kodzie: komentarze, docstrings
● Wiedza plemienna
● Inne źródła wiedzy

13. Sphinx-doc
Python documentation
generator
Github :: official docs
Czym to skleić razem?

14. Instalacja
Sphinx-doc:
apt-get install -y sphinx-doc
sphinx-rtd-theme-common
python-sphinxcontrib-*
Python pip / virtualenv / pipenv
pipenv install sphinx

15. Konfiguracja
sphinx-quickstart
> Separate source and build directories (y/n) [n]:
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Create Makefile? (y/n) [y]:
source/conf.py

16. Konfiguracja
# domyślna konfiguracja sphinxa to source/conf.py
# czysty python z komentarzami
extlinks = {
'jira': ('https://comp.atlassian.net/browse/%s', 'JIRA '),
'bb': ( 'https://bitbucket.org/comp/repo/pull-requests/%s','BitBucket'),
}
linkcheck_ignore = [
'https://internal.site/*',
'http://example.com/*',
]

17. Index.rst
Welcome to example!
===================
.. toctree::
:maxdepth: 2
:caption: Contents:
example
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

18. Budowanie

19. Przestroga

21. reStructuredText
● Język do tworzenia dokumentacji
● Oparty na znacznikach
● Bardzo łatwo przejść z MarkDown na reST
● Można konwertować .md na .rst
● Złożone projekty pokazują jego wyższość nad .md
● Krótki wstęp

22. example.rst
Examples of reST
================
- URL: `Official docutils page
<http://docutils.sourceforge.net/>`_
- URL: Quick reStructuredText reference_
.. _reference:
http://docutils.sourceforge.net/docs/user/rst/quickref.html
Code:
.. code:: json
{ "some_key": "some value", "other_key": 42 }
Lists
-----
Lists:
#. one
- bullet1
- bullet2
#. two
Images
------
.. image:: _static/images/test.prod.png

23. example.rst

24. Sphinx - Kilka bajerów
● Makefile i dodatkowe komendy
● Inne formaty wyjściowe - epub, pdf...
● Skórki (themes)
● Rozszerzenia

25. Makefile
● linkcheck
● changes
● doctest/coverage

26. linkcheck

27. Inne formaty
● single html / dir html
● epub, man pages...
● PDF - texlive-latex-extra albo ...-full

28. Skórki

29. Skórki

30. Skórki

31. Skórki

32. Rozszerzenia
● extensions
● sphinx contrib
● github awesome-sphinxdoc
● sphinx survey

33. Rozszerzenia
● autodoc
● napoleon / numpy
● autosummary / todo
● releases / git
● versioning

34. Rozszerzenia
● extlinks
● intersphinx
● viewcode
● issue tracker

35. Rozszerzenia
● graphviz
● blockdiag / sdedit
● aafig (aafigure)
● plantUML

36. Rozszerzenia
● programoutput
● autoprogram
● argparse

37. Rozszerzenia
● hieroglyph
● tut
● autobuild

38. Rozszerzenia
● sphinx-me
● confluence
● sphinx-to-github

39. Ansible?

40. Ansible
● playbooki + sekcje komentarzy
● sphinx-autoyaml

41. Sphinx
#conf.py
# extensions
extensions = [
'sphinxcontrib.autoyaml',
]
# autoyaml, relative to makefile location
autoyaml_root = './'
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
pipenv install sphinxcontrib-autoyaml
pipenv install sphinx_rtd_theme

42. Ansible deploy_etcd.yml
###
#
# Deploy etcd cluster
# -------------------
#
# Requirements
# ~~~~~~~~~~~~
# - playbook <base>.yml + <provider>.yml
#
# Features
# ~~~~~~~~
# - parallel provision if cluster is fresh
# - sequential rolling upgrade without downtime if cluster already exists
#
###
---

43. index.rst
Welcome to example!
===================
.. toctree::
:maxdepth: 2
:caption: Contents:
example
etcd

44. etcd.rst
Deploy ETCD cluster
===================
.. autoyaml:: ../deploy_etcd.yml
Some other text goes here...
make clean html

45. etcd.rst
###
#
# Deploy etcd cluster
# -------------------
#
# .. warning::
#
# Read carefully before doing upgrades to v3.2.10
#
# Parameters
# ~~~~~~~~~~
# - ``etcd_version`` - use custom etcd version, for example `v3.2.12`
# - ``etcd_defrag`` - `true` or `false`
###

47. Moduły
● Moduły: czysty python + docstrings
● Ansible Docs

48. Co dalej?
● Role i README.md

49. Co dalej?
● Inne dodatki

50. Co dalej?
● Przykłady: Matplotlib docs / Blender
● doc8 do sprawdzania składni .rst
● Ansible / Jenkins + autoprogram
● Write the docs
● Ops report card
● Openstack Reno release notes

51. Pytania?

52. Dziękuję za uwagę.