SlideShare a Scribd company logo
Software Documentation is
fun if you have the proper
tools
Introducing Sphinx
1#engageug
Write documentation that
• is inviting and clear
• is comprehensive, detailing all aspects of the project
• is skimmable
• offers examples of how to use the software
• has repetition, when useful
• is up-to-date
• is easy to contribute to
• is easy to find
Source: https://www.oreilly.com/ideas/the-eight-rules-of-good-documentation 2#engageug
About Me
Andrew Magerman
IBM Champion 2016-2019
Organises the Swiss Notes User Group (this November)
3#engageug
Mandate 2018: document AlohaDXP
4#engageug
Tools we don’t want
• Word – too much magic
• Wikis – no control over formatting, no transferability
• Markdown?
• Too many flavours
• References and cross-references soon become a pain
• There is a plaintext markup language specifically for
software documentation: reStructuredText
• And a documentation generation tool: Sphinx
5#engageug
reStructuredText
• Silly name
• Single Version!
• Very pithy
• Contains *directives* = ‘commands’
Pycharm and Visual code have syntax highlighting
6#engageug
Introducing Sphinx
• Open Source
• Originally for Python documentation
• Getting traction in other tech
• Uses reStructuredText + additional directives
• Appearance controlled by themes
7#engageug
classic theme
8#engageug
sphinxdoc theme
9#engageug
alabaster theme
10#engageug
sphinx-rtd-theme
11#engageug
custom theme
12#engageug
Sphinx Advantages
• Output formats:
• pdf through LaTeX
• searchable website
• Hierarchical Structure
• Syntax highlighting
• References and Cross-References
• Version Control
13#engageug
code-block and literalinclude
14#engageug
tables
15#engageug
refs + structure + admonition
16#engageug
glossary
17#engageug
make latexpdf
18#engageug
Installing Sphinx – the pain, the pain
• Download half the internet
• Install Python 3
• Install sphinx-doc
• Install LaTeX
• Install sphinx-autobuild
• Make sure you run python within a virtual environment
• or die a thousand dependency deaths
19#engageug
Controlling Sphinx
• sphinx-quickstart creates the directory structure
• defaults are good
• Root: _build, Makefile, make.bat, conf.py, index.rst
• sphinx-build builds the output
• Nice wrapper Makefile for it
• make clean html latexpdf
20#engageug
sphinx-autobuild for live updates
• watches a directory and triggers a new rendering
• Good with two screens
21#engageug
Customizing sphinx-doc with conf.py
• conf.py – always gets executed
• add sphinx extensions (e.g. graphviz)
• determine theme and theme options
• pointer to static files (like css..)
• LaTeX customiziations
22#engageug
Which editor?
• My favourite: PyCharm
• good syntax highlighting
• good renederer, Sphinx directives not supported
• VIsual Code has also renderers
23#engageug
Gotchas
• Python
• use a virtual environment.
• reStructuredText
• A completely empty line separates paragraphs
• Two lines for rendering of code-block
• Indentation is important!
• Parameters for attributes must have the same indentation
• an indent is three spaces
24#engageug
What about hosting?
• readthedocs.org provides free hosting of your
documentation
• Can link a Webhook for continuous documentation
• new push to master  new docs
25#engageug
Want developers to write documentation?
• Don’t make them switch context
• Don’t force them to use tools they hate
• Don’t make them think about presentation and
prettiness
• When I presented Sphinx to the developers…
26#engageug
The eight rules of good documentation
• Write documentation that
• is inviting and clear
• is comprehensive, detailing all aspects of the project
• is skimmable
• offers examples of how to use the software
• has repetition, when useful
• is up-to-date
• is easy to contribute to
• is easy to find
Source: https://www.oreilly.com/ideas/the-eight-rules-of-good-documentation
27#engageug
Links
• reStructuredText:
• http://docutils.sourceforge.net/rst.html
• sphinx:
• http://www.sphinx-doc.org/en/master/
• sphinx-autobuild:
• https://pypi.org/project/sphinx-autobuild/
• Python virtual environment:
• https://docs.python.org/3/library/venv.html
28#engageug
About Me
Andrew Magerman
andrew@magerman.com
IBM Champion 2016-2019
Organises the Swiss Notes User Group (this November)
29#engageug

More Related Content

What's hot

Untangling - fall2017 - week 9
Untangling - fall2017 - week 9Untangling - fall2017 - week 9
Untangling - fall2017 - week 9
Derek Jacoby
 
Continuous Integration with Open Source Tools - PHPUgFfm 2014-11-20
Continuous Integration with Open Source Tools - PHPUgFfm 2014-11-20Continuous Integration with Open Source Tools - PHPUgFfm 2014-11-20
Continuous Integration with Open Source Tools - PHPUgFfm 2014-11-20
Michael Lihs
 
Untangling spring week11
Untangling spring week11Untangling spring week11
Untangling spring week11
Derek Jacoby
 
The Architect Way
The Architect WayThe Architect Way
The Architect Way
Jan Jongboom
 
O365Con18 - Working with PowerShell, VS Code and GitHub - Thomas Vochten
O365Con18 - Working with PowerShell, VS Code and GitHub - Thomas VochtenO365Con18 - Working with PowerShell, VS Code and GitHub - Thomas Vochten
O365Con18 - Working with PowerShell, VS Code and GitHub - Thomas Vochten
NCCOMMS
 
Powerful Automation Made Simple
Powerful Automation Made SimplePowerful Automation Made Simple
Powerful Automation Made Simple
Gaetano Giunta
 
Azure Functions
Azure FunctionsAzure Functions
Azure Functions
Rodolfo Finochietti
 
Delivery Free of Charge
Delivery Free of ChargeDelivery Free of Charge
Delivery Free of Charge
All Things Open
 
Codecoon - A technical Case Study
Codecoon - A technical Case StudyCodecoon - A technical Case Study
Codecoon - A technical Case Study
Michael Lihs
 
Building our App with React Native
Building our App with React NativeBuilding our App with React Native
Building our App with React Native
Nuxeo
 
WordPress Development Environments
WordPress Development EnvironmentsWordPress Development Environments
WordPress Development Environments
Josh Cummings
 
Shift Remote: JS - Javascript Build Tools: Past & Beyond - Shedrack Akintayo
Shift Remote: JS - Javascript Build Tools: Past & Beyond - Shedrack Akintayo Shift Remote: JS - Javascript Build Tools: Past & Beyond - Shedrack Akintayo
Shift Remote: JS - Javascript Build Tools: Past & Beyond - Shedrack Akintayo
Shift Conference
 
Managing Changes to the Database Across the Project Life Cycle (presented by ...
Managing Changes to the Database Across the Project Life Cycle (presented by ...Managing Changes to the Database Across the Project Life Cycle (presented by ...
Managing Changes to the Database Across the Project Life Cycle (presented by ...
eZ Systems
 
Untangling11
Untangling11Untangling11
Untangling11
Derek Jacoby
 
Untangling - fall2017 - week 10
Untangling - fall2017 - week 10Untangling - fall2017 - week 10
Untangling - fall2017 - week 10
Derek Jacoby
 
AWS for the Java Developer
AWS for the Java DeveloperAWS for the Java Developer
AWS for the Java Developer
Rory Preddy
 
Dev112 let's calendar that
Dev112   let's calendar thatDev112   let's calendar that
Dev112 let's calendar that
Howard Greenberg
 
Starting from scratch in 2017
Starting from scratch in 2017Starting from scratch in 2017
Starting from scratch in 2017
Stefano Bonetta
 
Front-End Tools and Workflows
Front-End Tools and WorkflowsFront-End Tools and Workflows
Front-End Tools and Workflows
Sara Vieira
 
Que hay de nuevo en Visual Studio 2013 y ASP.NET 5.1
Que hay de nuevo en Visual Studio 2013 y ASP.NET 5.1Que hay de nuevo en Visual Studio 2013 y ASP.NET 5.1
Que hay de nuevo en Visual Studio 2013 y ASP.NET 5.1
Rodolfo Finochietti
 

What's hot (20)

Untangling - fall2017 - week 9
Untangling - fall2017 - week 9Untangling - fall2017 - week 9
Untangling - fall2017 - week 9
 
Continuous Integration with Open Source Tools - PHPUgFfm 2014-11-20
Continuous Integration with Open Source Tools - PHPUgFfm 2014-11-20Continuous Integration with Open Source Tools - PHPUgFfm 2014-11-20
Continuous Integration with Open Source Tools - PHPUgFfm 2014-11-20
 
Untangling spring week11
Untangling spring week11Untangling spring week11
Untangling spring week11
 
The Architect Way
The Architect WayThe Architect Way
The Architect Way
 
O365Con18 - Working with PowerShell, VS Code and GitHub - Thomas Vochten
O365Con18 - Working with PowerShell, VS Code and GitHub - Thomas VochtenO365Con18 - Working with PowerShell, VS Code and GitHub - Thomas Vochten
O365Con18 - Working with PowerShell, VS Code and GitHub - Thomas Vochten
 
Powerful Automation Made Simple
Powerful Automation Made SimplePowerful Automation Made Simple
Powerful Automation Made Simple
 
Azure Functions
Azure FunctionsAzure Functions
Azure Functions
 
Delivery Free of Charge
Delivery Free of ChargeDelivery Free of Charge
Delivery Free of Charge
 
Codecoon - A technical Case Study
Codecoon - A technical Case StudyCodecoon - A technical Case Study
Codecoon - A technical Case Study
 
Building our App with React Native
Building our App with React NativeBuilding our App with React Native
Building our App with React Native
 
WordPress Development Environments
WordPress Development EnvironmentsWordPress Development Environments
WordPress Development Environments
 
Shift Remote: JS - Javascript Build Tools: Past & Beyond - Shedrack Akintayo
Shift Remote: JS - Javascript Build Tools: Past & Beyond - Shedrack Akintayo Shift Remote: JS - Javascript Build Tools: Past & Beyond - Shedrack Akintayo
Shift Remote: JS - Javascript Build Tools: Past & Beyond - Shedrack Akintayo
 
Managing Changes to the Database Across the Project Life Cycle (presented by ...
Managing Changes to the Database Across the Project Life Cycle (presented by ...Managing Changes to the Database Across the Project Life Cycle (presented by ...
Managing Changes to the Database Across the Project Life Cycle (presented by ...
 
Untangling11
Untangling11Untangling11
Untangling11
 
Untangling - fall2017 - week 10
Untangling - fall2017 - week 10Untangling - fall2017 - week 10
Untangling - fall2017 - week 10
 
AWS for the Java Developer
AWS for the Java DeveloperAWS for the Java Developer
AWS for the Java Developer
 
Dev112 let's calendar that
Dev112   let's calendar thatDev112   let's calendar that
Dev112 let's calendar that
 
Starting from scratch in 2017
Starting from scratch in 2017Starting from scratch in 2017
Starting from scratch in 2017
 
Front-End Tools and Workflows
Front-End Tools and WorkflowsFront-End Tools and Workflows
Front-End Tools and Workflows
 
Que hay de nuevo en Visual Studio 2013 y ASP.NET 5.1
Que hay de nuevo en Visual Studio 2013 y ASP.NET 5.1Que hay de nuevo en Visual Studio 2013 y ASP.NET 5.1
Que hay de nuevo en Visual Studio 2013 y ASP.NET 5.1
 

Similar to Engage 2019 Software documentation is fun if you have the right tools: Introducing Sphinx

Markup languages and warp-speed documentation
Markup languages and warp-speed documentationMarkup languages and warp-speed documentation
Markup languages and warp-speed documentation
Lois Patterson
 
Lois Patterson: Markup Languages and Warp-Speed Documentation
Lois Patterson:  Markup Languages and Warp-Speed DocumentationLois Patterson:  Markup Languages and Warp-Speed Documentation
Lois Patterson: Markup Languages and Warp-Speed Documentation
Jack Molisani
 
Code the docs-yu liu
Code the docs-yu liuCode the docs-yu liu
Code the docs-yu liu
StreamNative
 
Revamping Mailjet API documentation @ ParisAPI meetup
Revamping Mailjet API documentation @ ParisAPI meetupRevamping Mailjet API documentation @ ParisAPI meetup
Revamping Mailjet API documentation @ ParisAPI meetup
Mailjet
 
Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018
Den Delimarsky
 
Rapid development of help files and user documentation in Dr.Explain 5
Rapid development of help files and user documentation in Dr.Explain 5Rapid development of help files and user documentation in Dr.Explain 5
Rapid development of help files and user documentation in Dr.Explain 5
Dennis Zhuravlev (a.k.a. Crane)
 
Python for security professionals by katoh jeremiah [py con ng 2018]
Python for security professionals by katoh jeremiah [py con ng 2018]Python for security professionals by katoh jeremiah [py con ng 2018]
Python for security professionals by katoh jeremiah [py con ng 2018]
jerrykatoh
 
Magento 2 Development Best Practices
Magento 2 Development Best PracticesMagento 2 Development Best Practices
Magento 2 Development Best Practices
Ben Marks
 
Best IDE for Programming in 2023 | Top 8 Programming IDE You Should Know | Si...
Best IDE for Programming in 2023 | Top 8 Programming IDE You Should Know | Si...Best IDE for Programming in 2023 | Top 8 Programming IDE You Should Know | Si...
Best IDE for Programming in 2023 | Top 8 Programming IDE You Should Know | Si...
Simplilearn
 
C#: Past, Present and Future
C#: Past, Present and FutureC#: Past, Present and Future
C#: Past, Present and Future
Rodolfo Finochietti
 
Communication tool & Environment for Remote Worker
Communication tool & Environment for Remote WorkerCommunication tool & Environment for Remote Worker
Communication tool & Environment for Remote Worker
Shotaro Sakamaki
 
Domain Specific Development using T4
Domain Specific Development using T4Domain Specific Development using T4
Domain Specific Development using T4
Joubin Najmaie
 
NetWork - 15.10.2011 - Applied code generation in .NET
NetWork - 15.10.2011 - Applied code generation in .NET NetWork - 15.10.2011 - Applied code generation in .NET
NetWork - 15.10.2011 - Applied code generation in .NET
Dmytro Mindra
 
Tooling for the JavaScript Era
Tooling for the JavaScript EraTooling for the JavaScript Era
Tooling for the JavaScript Era
martinlippert
 
Querix 4 gl app analyzer 2016 journey to the center of your 4gl application
Querix 4 gl app analyzer 2016 journey to the center of your 4gl applicationQuerix 4 gl app analyzer 2016 journey to the center of your 4gl application
Querix 4 gl app analyzer 2016 journey to the center of your 4gl application
BeGooden-IT Consulting
 
Building gRPC services
Building gRPC servicesBuilding gRPC services
Building gRPC services
Robert Robinson
 
Git and GitHub for Documentation
Git and GitHub for DocumentationGit and GitHub for Documentation
Git and GitHub for Documentation
Anne Gentle
 
Go - A Key Language in Enterprise Application Development?
Go - A Key Language in Enterprise Application Development?Go - A Key Language in Enterprise Application Development?
Go - A Key Language in Enterprise Application Development?
C4Media
 
Modern .NET Ecosystem
Modern .NET EcosystemModern .NET Ecosystem
Modern .NET Ecosystem
Andrei Marukovich
 
Everyone wants (someone else) to do it: writing documentation for open source...
Everyone wants (someone else) to do it: writing documentation for open source...Everyone wants (someone else) to do it: writing documentation for open source...
Everyone wants (someone else) to do it: writing documentation for open source...
Jody Garnett
 

Similar to Engage 2019 Software documentation is fun if you have the right tools: Introducing Sphinx (20)

Markup languages and warp-speed documentation
Markup languages and warp-speed documentationMarkup languages and warp-speed documentation
Markup languages and warp-speed documentation
 
Lois Patterson: Markup Languages and Warp-Speed Documentation
Lois Patterson:  Markup Languages and Warp-Speed DocumentationLois Patterson:  Markup Languages and Warp-Speed Documentation
Lois Patterson: Markup Languages and Warp-Speed Documentation
 
Code the docs-yu liu
Code the docs-yu liuCode the docs-yu liu
Code the docs-yu liu
 
Revamping Mailjet API documentation @ ParisAPI meetup
Revamping Mailjet API documentation @ ParisAPI meetupRevamping Mailjet API documentation @ ParisAPI meetup
Revamping Mailjet API documentation @ ParisAPI meetup
 
Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018
 
Rapid development of help files and user documentation in Dr.Explain 5
Rapid development of help files and user documentation in Dr.Explain 5Rapid development of help files and user documentation in Dr.Explain 5
Rapid development of help files and user documentation in Dr.Explain 5
 
Python for security professionals by katoh jeremiah [py con ng 2018]
Python for security professionals by katoh jeremiah [py con ng 2018]Python for security professionals by katoh jeremiah [py con ng 2018]
Python for security professionals by katoh jeremiah [py con ng 2018]
 
Magento 2 Development Best Practices
Magento 2 Development Best PracticesMagento 2 Development Best Practices
Magento 2 Development Best Practices
 
Best IDE for Programming in 2023 | Top 8 Programming IDE You Should Know | Si...
Best IDE for Programming in 2023 | Top 8 Programming IDE You Should Know | Si...Best IDE for Programming in 2023 | Top 8 Programming IDE You Should Know | Si...
Best IDE for Programming in 2023 | Top 8 Programming IDE You Should Know | Si...
 
C#: Past, Present and Future
C#: Past, Present and FutureC#: Past, Present and Future
C#: Past, Present and Future
 
Communication tool & Environment for Remote Worker
Communication tool & Environment for Remote WorkerCommunication tool & Environment for Remote Worker
Communication tool & Environment for Remote Worker
 
Domain Specific Development using T4
Domain Specific Development using T4Domain Specific Development using T4
Domain Specific Development using T4
 
NetWork - 15.10.2011 - Applied code generation in .NET
NetWork - 15.10.2011 - Applied code generation in .NET NetWork - 15.10.2011 - Applied code generation in .NET
NetWork - 15.10.2011 - Applied code generation in .NET
 
Tooling for the JavaScript Era
Tooling for the JavaScript EraTooling for the JavaScript Era
Tooling for the JavaScript Era
 
Querix 4 gl app analyzer 2016 journey to the center of your 4gl application
Querix 4 gl app analyzer 2016 journey to the center of your 4gl applicationQuerix 4 gl app analyzer 2016 journey to the center of your 4gl application
Querix 4 gl app analyzer 2016 journey to the center of your 4gl application
 
Building gRPC services
Building gRPC servicesBuilding gRPC services
Building gRPC services
 
Git and GitHub for Documentation
Git and GitHub for DocumentationGit and GitHub for Documentation
Git and GitHub for Documentation
 
Go - A Key Language in Enterprise Application Development?
Go - A Key Language in Enterprise Application Development?Go - A Key Language in Enterprise Application Development?
Go - A Key Language in Enterprise Application Development?
 
Modern .NET Ecosystem
Modern .NET EcosystemModern .NET Ecosystem
Modern .NET Ecosystem
 
Everyone wants (someone else) to do it: writing documentation for open source...
Everyone wants (someone else) to do it: writing documentation for open source...Everyone wants (someone else) to do it: writing documentation for open source...
Everyone wants (someone else) to do it: writing documentation for open source...
 

Recently uploaded

Sonkoloniya documentation - ONEprojukti.pdf
Sonkoloniya documentation - ONEprojukti.pdfSonkoloniya documentation - ONEprojukti.pdf
Sonkoloniya documentation - ONEprojukti.pdf
SubhamMandal40
 
Semantic-Aware Code Model: Elevating the Future of Software Development
Semantic-Aware Code Model: Elevating the Future of Software DevelopmentSemantic-Aware Code Model: Elevating the Future of Software Development
Semantic-Aware Code Model: Elevating the Future of Software Development
Baishakhi Ray
 
Girls Call Churchgate 9910780858 Provide Best And Top Girl Service And No1 in...
Girls Call Churchgate 9910780858 Provide Best And Top Girl Service And No1 in...Girls Call Churchgate 9910780858 Provide Best And Top Girl Service And No1 in...
Girls Call Churchgate 9910780858 Provide Best And Top Girl Service And No1 in...
maigasapphire
 
MAKE MONEY ONLINE Unlock Your Income Potential Today.pptx
MAKE MONEY ONLINE Unlock Your Income Potential Today.pptxMAKE MONEY ONLINE Unlock Your Income Potential Today.pptx
MAKE MONEY ONLINE Unlock Your Income Potential Today.pptx
janagijoythi
 
Feature sql server terbaru performance.pptx
Feature sql server terbaru performance.pptxFeature sql server terbaru performance.pptx
Feature sql server terbaru performance.pptx
ssuser1915fe1
 
Mastering OnlyFans Clone App Development: Key Strategies for Success
Mastering OnlyFans Clone App Development: Key Strategies for SuccessMastering OnlyFans Clone App Development: Key Strategies for Success
Mastering OnlyFans Clone App Development: Key Strategies for Success
David Wilson
 
Zaitechno Handheld Raman Spectrometer.pdf
Zaitechno Handheld Raman Spectrometer.pdfZaitechno Handheld Raman Spectrometer.pdf
Zaitechno Handheld Raman Spectrometer.pdf
AmandaCheung15
 
Google I/O Extended Harare Merged Slides
Google I/O Extended Harare Merged SlidesGoogle I/O Extended Harare Merged Slides
Google I/O Extended Harare Merged Slides
Google Developer Group - Harare
 
Tailored CRM Software Development for Enhanced Customer Insights
Tailored CRM Software Development for Enhanced Customer InsightsTailored CRM Software Development for Enhanced Customer Insights
Tailored CRM Software Development for Enhanced Customer Insights
SynapseIndia
 
High Profile Girls call Service Pune 000XX00000 Provide Best And Top Girl Ser...
High Profile Girls call Service Pune 000XX00000 Provide Best And Top Girl Ser...High Profile Girls call Service Pune 000XX00000 Provide Best And Top Girl Ser...
High Profile Girls call Service Pune 000XX00000 Provide Best And Top Girl Ser...
bhumivarma35300
 
leewayhertz.com-Generative AI tech stack Frameworks infrastructure models and...
leewayhertz.com-Generative AI tech stack Frameworks infrastructure models and...leewayhertz.com-Generative AI tech stack Frameworks infrastructure models and...
leewayhertz.com-Generative AI tech stack Frameworks infrastructure models and...
alexjohnson7307
 
Types of Weaving loom machine & it's technology
Types of Weaving loom machine & it's technologyTypes of Weaving loom machine & it's technology
Types of Weaving loom machine & it's technology
ldtexsolbl
 
Opencast Summit 2024 — Opencast @ University of Münster
Opencast Summit 2024 — Opencast @ University of MünsterOpencast Summit 2024 — Opencast @ University of Münster
Opencast Summit 2024 — Opencast @ University of Münster
Matthias Neugebauer
 
The History of Embeddings & Multimodal Embeddings
The History of Embeddings & Multimodal EmbeddingsThe History of Embeddings & Multimodal Embeddings
The History of Embeddings & Multimodal Embeddings
Zilliz
 
Use Cases & Benefits of RPA in Manufacturing in 2024.pptx
Use Cases & Benefits of RPA in Manufacturing in 2024.pptxUse Cases & Benefits of RPA in Manufacturing in 2024.pptx
Use Cases & Benefits of RPA in Manufacturing in 2024.pptx
SynapseIndia
 
How UiPath Discovery Suite supports identification of Agentic Process Automat...
How UiPath Discovery Suite supports identification of Agentic Process Automat...How UiPath Discovery Suite supports identification of Agentic Process Automat...
How UiPath Discovery Suite supports identification of Agentic Process Automat...
DianaGray10
 
Mule Experience Hub and Release Channel with Java 17
Mule Experience Hub and Release Channel with Java 17Mule Experience Hub and Release Channel with Java 17
Mule Experience Hub and Release Channel with Java 17
Bhajan Mehta
 
Vulnerability Management: A Comprehensive Overview
Vulnerability Management: A Comprehensive OverviewVulnerability Management: A Comprehensive Overview
Vulnerability Management: A Comprehensive Overview
Steven Carlson
 
Generative AI Reasoning Tech Talk - July 2024
Generative AI Reasoning Tech Talk - July 2024Generative AI Reasoning Tech Talk - July 2024
Generative AI Reasoning Tech Talk - July 2024
siddu769252
 
Communications Mining Series - Zero to Hero - Session 3
Communications Mining Series - Zero to Hero - Session 3Communications Mining Series - Zero to Hero - Session 3
Communications Mining Series - Zero to Hero - Session 3
DianaGray10
 

Recently uploaded (20)

Sonkoloniya documentation - ONEprojukti.pdf
Sonkoloniya documentation - ONEprojukti.pdfSonkoloniya documentation - ONEprojukti.pdf
Sonkoloniya documentation - ONEprojukti.pdf
 
Semantic-Aware Code Model: Elevating the Future of Software Development
Semantic-Aware Code Model: Elevating the Future of Software DevelopmentSemantic-Aware Code Model: Elevating the Future of Software Development
Semantic-Aware Code Model: Elevating the Future of Software Development
 
Girls Call Churchgate 9910780858 Provide Best And Top Girl Service And No1 in...
Girls Call Churchgate 9910780858 Provide Best And Top Girl Service And No1 in...Girls Call Churchgate 9910780858 Provide Best And Top Girl Service And No1 in...
Girls Call Churchgate 9910780858 Provide Best And Top Girl Service And No1 in...
 
MAKE MONEY ONLINE Unlock Your Income Potential Today.pptx
MAKE MONEY ONLINE Unlock Your Income Potential Today.pptxMAKE MONEY ONLINE Unlock Your Income Potential Today.pptx
MAKE MONEY ONLINE Unlock Your Income Potential Today.pptx
 
Feature sql server terbaru performance.pptx
Feature sql server terbaru performance.pptxFeature sql server terbaru performance.pptx
Feature sql server terbaru performance.pptx
 
Mastering OnlyFans Clone App Development: Key Strategies for Success
Mastering OnlyFans Clone App Development: Key Strategies for SuccessMastering OnlyFans Clone App Development: Key Strategies for Success
Mastering OnlyFans Clone App Development: Key Strategies for Success
 
Zaitechno Handheld Raman Spectrometer.pdf
Zaitechno Handheld Raman Spectrometer.pdfZaitechno Handheld Raman Spectrometer.pdf
Zaitechno Handheld Raman Spectrometer.pdf
 
Google I/O Extended Harare Merged Slides
Google I/O Extended Harare Merged SlidesGoogle I/O Extended Harare Merged Slides
Google I/O Extended Harare Merged Slides
 
Tailored CRM Software Development for Enhanced Customer Insights
Tailored CRM Software Development for Enhanced Customer InsightsTailored CRM Software Development for Enhanced Customer Insights
Tailored CRM Software Development for Enhanced Customer Insights
 
High Profile Girls call Service Pune 000XX00000 Provide Best And Top Girl Ser...
High Profile Girls call Service Pune 000XX00000 Provide Best And Top Girl Ser...High Profile Girls call Service Pune 000XX00000 Provide Best And Top Girl Ser...
High Profile Girls call Service Pune 000XX00000 Provide Best And Top Girl Ser...
 
leewayhertz.com-Generative AI tech stack Frameworks infrastructure models and...
leewayhertz.com-Generative AI tech stack Frameworks infrastructure models and...leewayhertz.com-Generative AI tech stack Frameworks infrastructure models and...
leewayhertz.com-Generative AI tech stack Frameworks infrastructure models and...
 
Types of Weaving loom machine & it's technology
Types of Weaving loom machine & it's technologyTypes of Weaving loom machine & it's technology
Types of Weaving loom machine & it's technology
 
Opencast Summit 2024 — Opencast @ University of Münster
Opencast Summit 2024 — Opencast @ University of MünsterOpencast Summit 2024 — Opencast @ University of Münster
Opencast Summit 2024 — Opencast @ University of Münster
 
The History of Embeddings & Multimodal Embeddings
The History of Embeddings & Multimodal EmbeddingsThe History of Embeddings & Multimodal Embeddings
The History of Embeddings & Multimodal Embeddings
 
Use Cases & Benefits of RPA in Manufacturing in 2024.pptx
Use Cases & Benefits of RPA in Manufacturing in 2024.pptxUse Cases & Benefits of RPA in Manufacturing in 2024.pptx
Use Cases & Benefits of RPA in Manufacturing in 2024.pptx
 
How UiPath Discovery Suite supports identification of Agentic Process Automat...
How UiPath Discovery Suite supports identification of Agentic Process Automat...How UiPath Discovery Suite supports identification of Agentic Process Automat...
How UiPath Discovery Suite supports identification of Agentic Process Automat...
 
Mule Experience Hub and Release Channel with Java 17
Mule Experience Hub and Release Channel with Java 17Mule Experience Hub and Release Channel with Java 17
Mule Experience Hub and Release Channel with Java 17
 
Vulnerability Management: A Comprehensive Overview
Vulnerability Management: A Comprehensive OverviewVulnerability Management: A Comprehensive Overview
Vulnerability Management: A Comprehensive Overview
 
Generative AI Reasoning Tech Talk - July 2024
Generative AI Reasoning Tech Talk - July 2024Generative AI Reasoning Tech Talk - July 2024
Generative AI Reasoning Tech Talk - July 2024
 
Communications Mining Series - Zero to Hero - Session 3
Communications Mining Series - Zero to Hero - Session 3Communications Mining Series - Zero to Hero - Session 3
Communications Mining Series - Zero to Hero - Session 3
 

Engage 2019 Software documentation is fun if you have the right tools: Introducing Sphinx

  • 1. Software Documentation is fun if you have the proper tools Introducing Sphinx 1#engageug
  • 2. Write documentation that • is inviting and clear • is comprehensive, detailing all aspects of the project • is skimmable • offers examples of how to use the software • has repetition, when useful • is up-to-date • is easy to contribute to • is easy to find Source: https://www.oreilly.com/ideas/the-eight-rules-of-good-documentation 2#engageug
  • 3. About Me Andrew Magerman IBM Champion 2016-2019 Organises the Swiss Notes User Group (this November) 3#engageug
  • 4. Mandate 2018: document AlohaDXP 4#engageug
  • 5. Tools we don’t want • Word – too much magic • Wikis – no control over formatting, no transferability • Markdown? • Too many flavours • References and cross-references soon become a pain • There is a plaintext markup language specifically for software documentation: reStructuredText • And a documentation generation tool: Sphinx 5#engageug
  • 6. reStructuredText • Silly name • Single Version! • Very pithy • Contains *directives* = ‘commands’ Pycharm and Visual code have syntax highlighting 6#engageug
  • 7. Introducing Sphinx • Open Source • Originally for Python documentation • Getting traction in other tech • Uses reStructuredText + additional directives • Appearance controlled by themes 7#engageug
  • 13. Sphinx Advantages • Output formats: • pdf through LaTeX • searchable website • Hierarchical Structure • Syntax highlighting • References and Cross-References • Version Control 13#engageug
  • 16. refs + structure + admonition 16#engageug
  • 19. Installing Sphinx – the pain, the pain • Download half the internet • Install Python 3 • Install sphinx-doc • Install LaTeX • Install sphinx-autobuild • Make sure you run python within a virtual environment • or die a thousand dependency deaths 19#engageug
  • 20. Controlling Sphinx • sphinx-quickstart creates the directory structure • defaults are good • Root: _build, Makefile, make.bat, conf.py, index.rst • sphinx-build builds the output • Nice wrapper Makefile for it • make clean html latexpdf 20#engageug
  • 21. sphinx-autobuild for live updates • watches a directory and triggers a new rendering • Good with two screens 21#engageug
  • 22. Customizing sphinx-doc with conf.py • conf.py – always gets executed • add sphinx extensions (e.g. graphviz) • determine theme and theme options • pointer to static files (like css..) • LaTeX customiziations 22#engageug
  • 23. Which editor? • My favourite: PyCharm • good syntax highlighting • good renederer, Sphinx directives not supported • VIsual Code has also renderers 23#engageug
  • 24. Gotchas • Python • use a virtual environment. • reStructuredText • A completely empty line separates paragraphs • Two lines for rendering of code-block • Indentation is important! • Parameters for attributes must have the same indentation • an indent is three spaces 24#engageug
  • 25. What about hosting? • readthedocs.org provides free hosting of your documentation • Can link a Webhook for continuous documentation • new push to master  new docs 25#engageug
  • 26. Want developers to write documentation? • Don’t make them switch context • Don’t force them to use tools they hate • Don’t make them think about presentation and prettiness • When I presented Sphinx to the developers… 26#engageug
  • 27. The eight rules of good documentation • Write documentation that • is inviting and clear • is comprehensive, detailing all aspects of the project • is skimmable • offers examples of how to use the software • has repetition, when useful • is up-to-date • is easy to contribute to • is easy to find Source: https://www.oreilly.com/ideas/the-eight-rules-of-good-documentation 27#engageug
  • 28. Links • reStructuredText: • http://docutils.sourceforge.net/rst.html • sphinx: • http://www.sphinx-doc.org/en/master/ • sphinx-autobuild: • https://pypi.org/project/sphinx-autobuild/ • Python virtual environment: • https://docs.python.org/3/library/venv.html 28#engageug
  • 29. About Me Andrew Magerman andrew@magerman.com IBM Champion 2016-2019 Organises the Swiss Notes User Group (this November) 29#engageug

Editor's Notes

  1. We’ll see some examples later
  2. I wouldn’t fiddle too much with the Themes
  3. man pages, ePub Let’s go through some code examples. I was not brave enough to live-code. I’m