Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

CodiLime Tech Talk - Michał Sochoń: Sphinx, reST & Ansible

56 views

Published on

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

Published in: Technology
  • Be the first to comment

  • Be the first to like this

CodiLime Tech Talk - Michał Sochoń: Sphinx, reST & Ansible

  1. 1. Sphinx, reST i Ansible Wprowadzenie do automatycznego generowania dokumentacji
  2. 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. 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. 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. 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. 6. Problem ● Nie chce mi się ● Brak czasu ● Permanentna zmiana ● Nie wiemy jak
  7. 7. Skutki ● O tamten w rogu wie... ● Chcą dokumentację teraz? ● Mam kogoś szkolić? ● Fajnie, że mamy internet ● FFFFFFFFFFF…..
  8. 8. Jak to naprawić? Napisać dokumentację.
  9. 9. Po co? ● Oszczędność czasu zespołu ● Logiczny podział wiedzy ● Różne scenariusze pracy ● Integracje
  10. 10. Jak to zrobić? ● Przejrzeć to co jest i dopisać ● Najlepiej trzymać w repo projektu ● Automatycznie generować i publikować ● Używać perswazji :)
  11. 11. Przejrzenie tego co jest ● Istniejące dokumenty ● W kodzie: komentarze, docstrings ● Wiedza plemienna ● Inne źródła wiedzy
  12. 12. Sphinx-doc Python documentation generator Github :: official docs Czym to skleić razem?
  13. 13. Instalacja Sphinx-doc: apt-get install -y sphinx-doc sphinx-rtd-theme-common python-sphinxcontrib-* Python pip / virtualenv / pipenv pipenv install sphinx
  14. 14. 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
  15. 15. 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/*', ]
  16. 16. Index.rst Welcome to example! =================== .. toctree:: :maxdepth: 2 :caption: Contents: example Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
  17. 17. Budowanie
  18. 18. Przestroga
  19. 19. 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
  20. 20. 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
  21. 21. example.rst
  22. 22. Sphinx - Kilka bajerów ● Makefile i dodatkowe komendy ● Inne formaty wyjściowe - epub, pdf... ● Skórki (themes) ● Rozszerzenia
  23. 23. Makefile ● linkcheck ● changes ● doctest/coverage
  24. 24. linkcheck
  25. 25. Inne formaty ● single html / dir html ● epub, man pages... ● PDF - texlive-latex-extra albo ...-full
  26. 26. Skórki
  27. 27. Skórki
  28. 28. Skórki
  29. 29. Skórki
  30. 30. Rozszerzenia ● extensions ● sphinx contrib ● github awesome-sphinxdoc ● sphinx survey
  31. 31. Rozszerzenia ● autodoc ● napoleon / numpy ● autosummary / todo ● releases / git ● versioning
  32. 32. Rozszerzenia ● extlinks ● intersphinx ● viewcode ● issue tracker
  33. 33. Rozszerzenia ● graphviz ● blockdiag / sdedit ● aafig (aafigure) ● plantUML
  34. 34. Rozszerzenia ● programoutput ● autoprogram ● argparse
  35. 35. Rozszerzenia ● hieroglyph ● tut ● autobuild
  36. 36. Rozszerzenia ● sphinx-me ● confluence ● sphinx-to-github
  37. 37. Ansible?
  38. 38. Ansible ● playbooki + sekcje komentarzy ● sphinx-autoyaml
  39. 39. 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
  40. 40. 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 # ### ---
  41. 41. index.rst Welcome to example! =================== .. toctree:: :maxdepth: 2 :caption: Contents: example etcd
  42. 42. etcd.rst Deploy ETCD cluster =================== .. autoyaml:: ../deploy_etcd.yml Some other text goes here... make clean html
  43. 43. 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` ###
  44. 44. Moduły ● Moduły: czysty python + docstrings ● Ansible Docs
  45. 45. Co dalej? ● Role i README.md
  46. 46. Co dalej? ● Inne dodatki
  47. 47. 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
  48. 48. Pytania?
  49. 49. Dziękuję za uwagę.

×