Enhancing Documentations on Sphinx with the Power of Sphinx

Slides for talk delivered at PyCon APAC 2022.

Transcript

1. Enhancing Documentations on Sphinx with the Power of Extensions RENALDI GONDOSUBROTO
2. 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
3. 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
4. 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
5. The Different Kinds of Documentation • Tutorials • How-tos • Explanations • Reference guides PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 5
6. 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
7. Hierarchy of Documentations PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 7
8. 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
9. Creating Markup Extensions Sphinx Node Directive Event Handlers PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 9
10. The Setup PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 10
11. Directive Classes PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 11
12. Event Handler: PurgeDoc PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 12
13. Event Handler: Process Custom Nodes PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 13
14. 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
15. 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
16. 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
17. 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
18. 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
19. 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!
20. 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
21. PyCon APAC 2022 Enhancing Documentations on Sphinx with the Power of Extensions 21 Thank you Questions? Contact Me At renaldigondosubroto@yahoo.com Connect with me! @Renaldig @renaldigondosubroto