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

Enhancing Documentations on Sphinx with the Pow...

Enhancing Documentations on Sphinx with the Power of Sphinx

Slides for talk delivered at PyCon APAC 2022.

Renaldi Gondosubroto

August 31, 2022
Tweet

More Decks by Renaldi Gondosubroto

Other Decks in Programming

Transcript

  1. PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power

    of Extensions 2 A Bit About Myself • 12x AWS, 2x Microsoft Azure Expert Certified and 7x Google Cloud Certified • Personal field of interest is in cloud-based developments and project management • On the side: Running meetups, hackathons, doing tech talks and VR tech enthusiast Renaldi Gondosubroto, CSCP, PMP, PMI-ACP Project Lead and Developer Advocate @ GReS Studio @Renaldig @renaldigondosubroto
  2. Agenda 1. Why document with Sphinx? 2. Creating Markup Processors

    3. Current Trends in Developing Extensions 4. Key Considerations in Development 5. Case Study of Custom Markup Processor Extension PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 3
  3. The Importance of Documentation • Change of personnel • Working

    with many people across many teams • A form of politeness and respect to the next developer PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 4
  4. The Different Kinds of Documentation • Tutorials • How-tos •

    Explanations • Reference guides PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 5
  5. Why Sphinx? PyCon APAC 2022 Enhancing Documentations on Sphinx with

    the Power of Extensions 6 • Written as plain text files • Many different layouts can be used • Autogenerating documentation based on source code • Developer can focus on content, layout and output provided by Sphinx • Cross-references to different parts of documentation • Version control with GitHub can be used • Documentation part of source code repo • Catch errors as part of sphinx-build, captured on stderr/stdout
  6. Build Phases • Phase 0: Initialization • Phase 1: Reading

    • Phase 2: Consistency Checks • Phase 3: Resolving • Phase 4: Writing PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 8
  7. Creating Markup Extensions Sphinx Node Directive Event Handlers PyCon APAC

    2022 Enhancing Documentations on Sphinx with the Power of Extensions 9
  8. Planning and Structuring Extensions customext-master ├── docs │ ├── build

    │ ├── make.bat │ ├── Makefile │ └── source ├── LICENSE ├── README.md ├── requirements.txt └── customext └── customext.py • Sphinx build root • Repository root • Documentation root PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 14
  9. Accessibility • Setting language in conf.py • A11y standards in

    writing for a general population • Be inclusive • Especially important where actions need to be taken such as links PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 15
  10. Case Study for Modern Practices • Need to implement extension

    for custom class iterating over SQL file • Derive benefits based on people referring to it • Need to serve it on the Cloud PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 16
  11. Serving Documentation on the Cloud • Setup IP restricted S3

    Bucket • Confirm policy if it exists • Defined policy document if not • Setup documentation built by synchronizing content of local folder with remote bucket • Configure S3 and operate as website with documentation PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 17
  12. Lessons Learned • Small pieces of documentation go a long

    way • Customize the content • Look for ways to modernize implementations PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 18
  13. Conclusion PyCon APAC 2022 Enhancing Documentations on Sphinx with the

    Power of Extensions 19 WORK WITH YOUR FELLOW DEVELOPERS LEARN FROM THE BEST PRACTICES DOCUMENT, DOCUMENT, DOCUMENT!
  14. 3 Biggest Software Lies: - The program's fully tested and

    bug-free. - We're working on the documentation. - Of course we can modify it. -Anonymous PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 20
  15. PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power

    of Extensions 21 Thank you Questions? Contact Me At [email protected] Connect with me! @Renaldig @renaldigondosubroto