SlideShare a Scribd company logo
Picture
Sphinx
documentation BoF
16 SEPTEMBER 2022
Copyright © SUSE 2022
2
Where do we have a documentation?
1) Web pages at gcc.gnu.org
●
development info and releases (changes, porting to)
●
git contribution (write access, development branches, ...)
●
GNU coding style; git ChangeLog format
●
open project info (C++ features, ...)
2)Texinfo documentation in git repository
●
User-Level Documentation
●
Internals Documentation
3)GCC WIKI at gcc.gnu.org/wiki
●
Cauldron events
●
List of historical and current projects
●
internal documentation (LTO plug-in API, LTO offloading, ...)
Copyright © SUSE 2022
3
What formats do we use?
1) Web pages at gcc.gnu.org
●
input: HTML
●
output: HTML
2)Texinfo documentation in git repository
●
input: Texinfo
●
output: manual pages, info, HTML and PDF
3)GCC wikipedia at gcc.gnu.org/wiki
●
input: wiki markup
●
output: HTML
Copyright © SUSE 2022
4
Who are documentation stakeholders?
1)Users (consume)
2)Developers (produce)
3)Package maintainers, people who build toolchain (produce &
consume)
Picture
Demo
Copyright © SUSE 2022
6
Limitations of the current documentation
●
Poor navigation (Next, Previous, Up, …)
●
No search capability (Google is workaround)
●
Poor formatting (font sizes, colours, spacing)
●
Poor link anchors (maybe fixed in latest Texinfo)
●
Almost no cross-references (definition vs. usage)
●
Missing extra features (code snippet highlighting, cross references, link
checking, …)
●
Limited set of directives/keywords
Copyright © SUSE 2022
7
Why moving to Sphinx?
●
we can address the aforementioned limitations
●
already being used (libgccjit, 3 Ada manuals)
●
ReStructuredText (RST) is a lightweight markup language
●
proved by many projects (Read the Docs, Python ecosystem, Linux kernel, ...)
Copyright © SUSE 2022
8
Limitations of Sphinx documentation
●
automatic conversion may contain errata
●
individual page map 1:1 to source file (100s of .rst files)
●
developers need to learn a new documentation format
●
git blame would become harder (still possible)
●
update_web_docs_git – needs to be ported
●
Sphinx warnings (duplicate definitions, attributes, …)
●
Downstream docs needs to be converted (Modula-2)
●
Python stack needed for GCC package build
Copyright © SUSE 2022
9
What extra will Sphinx bring us?
●
Intersphinx extension – cross manual references
●
Sphinx Themes – many options
●
Pygments – Python syntax highlighter
●
Linkcheck builder – verify all URLs
●
EPUB builder
●
Changes and Porting to are big candidates for migration
●
Intersphinx extension – cross manual references
●
Sphinx Themes – many options
●
Pygments – Python syntax highlighter
●
Linkcheck builder – verify all URLs
●
EPUB builder
●
Changes and Porting to are big candidates for migration
Copyright © SUSE 2022
10
Conversion details
●
makeinfo --xml is used
●
texi2rst.py – conversion script visits XML file and converts to RST
●
GitHub action runs texi2rst.py for GCC devel/sphinx branch
●
Manual changes are merged to automatically converted docs
●
post processing – GCC patch set
Copyright © SUSE 2022
11
Conclusion
●
Can I make the conversion?
●
What will be the best timing?
●
Questions?
Picture
Thank you.

More Related Content

KEY
Sphinx-quickstart
PDF
sphinx demo
PDF
Knoxbug2016
PDF
Lois Patterson: Markup Languages and Warp-Speed Documentation
PPTX
Markup languages and warp-speed documentation
PPTX
sphinx-i18n — The True Story
PPTX
Easy contributable internationalization process with Sphinx @ PyCon APAC 2016
PDF
Lfnw2016
Sphinx-quickstart
sphinx demo
Knoxbug2016
Lois Patterson: Markup Languages and Warp-Speed Documentation
Markup languages and warp-speed documentation
sphinx-i18n — The True Story
Easy contributable internationalization process with Sphinx @ PyCon APAC 2016
Lfnw2016

Similar to cauldron-2022-docs-bof at gcc cauldron in 2022 (20)

PPTX
Moving from Publican to Read The Docs
PDF
Challenge: convert policy doc from docbook to sphinx
PPTX
Life with Sphinx 2012 #sphinxconjp
PPTX
Easy contributable internationalization process with Sphinx @ pyconsg2015
PDF
Olf2016
PDF
Tlf2016
PDF
Kernel Recipes 2016 - Kernel documentation: what we have and where it’s going
PDF
忙しい人のためのSphinx 入門 demo
PDF
儲かるドキュメント
PDF
Scale2016
PPTX
Easy contributable internationalization process with Sphinx (PyCon APAC 2015 ...
PDF
Fossetcon15
PPTX
Engage 2019 Software documentation is fun if you have the right tools: Introd...
PPTX
Easy contributable internationalization process with Sphinx @ pyconmy2015
KEY
関西 Unconferance Sphinx かわいいよ Sphinx
PDF
Make an Instant Website with Webhooks
PPTX
Documentation with Sphinx
PPTX
Sphinx autodoc - automated api documentation - PyCon.KR 2015
PPTX
Sphinx autodoc - automated API documentation (PyCon APAC 2015 in Taiwan)
PPTX
Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Lov...
Moving from Publican to Read The Docs
Challenge: convert policy doc from docbook to sphinx
Life with Sphinx 2012 #sphinxconjp
Easy contributable internationalization process with Sphinx @ pyconsg2015
Olf2016
Tlf2016
Kernel Recipes 2016 - Kernel documentation: what we have and where it’s going
忙しい人のためのSphinx 入門 demo
儲かるドキュメント
Scale2016
Easy contributable internationalization process with Sphinx (PyCon APAC 2015 ...
Fossetcon15
Engage 2019 Software documentation is fun if you have the right tools: Introd...
Easy contributable internationalization process with Sphinx @ pyconmy2015
関西 Unconferance Sphinx かわいいよ Sphinx
Make an Instant Website with Webhooks
Documentation with Sphinx
Sphinx autodoc - automated api documentation - PyCon.KR 2015
Sphinx autodoc - automated API documentation (PyCon APAC 2015 in Taiwan)
Project Documentation with Sphinx (or, How I Learned to Stop Worrying and Lov...
Ad

More from ssuser866937 (11)

PDF
GNU Toolchain Infrastructure at gcc cauldron
PDF
Ctrl-C redesign for gcc cauldron in 2022 in prague
PDF
Cauldron_2022_ctf_frame at gcc cauldron 2022 in prague
PDF
BoF-OpenMP-OpenACC-Offloading-Cauldron2022.pdf
PDF
Anatomy of ROCgdb presentation at gcc cauldron 2022
PDF
2022-ranger-update-Cauldron for gcc versions
PDF
2022 Cauldron Value Numbering for gcc versions
PDF
2022-Cauldron-If-Conversion-for-a-Partially-Predicated-VLIW-Architecture.pdf
PDF
2022 Cauldron analyzer talk from david malcolm
PDF
OpenMP-OpenACC-Offload-Cauldron2022-1.pdf
PDF
cs.ds-2211.13454.pdf
GNU Toolchain Infrastructure at gcc cauldron
Ctrl-C redesign for gcc cauldron in 2022 in prague
Cauldron_2022_ctf_frame at gcc cauldron 2022 in prague
BoF-OpenMP-OpenACC-Offloading-Cauldron2022.pdf
Anatomy of ROCgdb presentation at gcc cauldron 2022
2022-ranger-update-Cauldron for gcc versions
2022 Cauldron Value Numbering for gcc versions
2022-Cauldron-If-Conversion-for-a-Partially-Predicated-VLIW-Architecture.pdf
2022 Cauldron analyzer talk from david malcolm
OpenMP-OpenACC-Offload-Cauldron2022-1.pdf
cs.ds-2211.13454.pdf
Ad

Recently uploaded (20)

PPTX
June-4-Sermon-Powerpoint.pptx USE THIS FOR YOUR MOTIVATION
PPTX
Introduction to cybersecurity and digital nettiquette
PPTX
SAP Ariba Sourcing PPT for learning material
DOCX
Unit-3 cyber security network security of internet system
PPTX
INTERNET------BASICS-------UPDATED PPT PRESENTATION
PDF
Unit-1 introduction to cyber security discuss about how to secure a system
PPTX
Introduction to Information and Communication Technology
PDF
Paper PDF World Game (s) Great Redesign.pdf
PDF
Tenda Login Guide: Access Your Router in 5 Easy Steps
PPTX
presentation_pfe-universite-molay-seltan.pptx
PPTX
innovation process that make everything different.pptx
PPTX
Slides PPTX World Game (s) Eco Economic Epochs.pptx
PDF
FINAL CALL-6th International Conference on Networks & IOT (NeTIOT 2025)
PPTX
Power Point - Lesson 3_2.pptx grad school presentation
PDF
Best Practices for Testing and Debugging Shopify Third-Party API Integrations...
PPTX
artificialintelligenceai1-copy-210604123353.pptx
PDF
Sims 4 Historia para lo sims 4 para jugar
PPTX
E -tech empowerment technologies PowerPoint
PDF
Slides PDF The World Game (s) Eco Economic Epochs.pdf
PDF
An introduction to the IFRS (ISSB) Stndards.pdf
June-4-Sermon-Powerpoint.pptx USE THIS FOR YOUR MOTIVATION
Introduction to cybersecurity and digital nettiquette
SAP Ariba Sourcing PPT for learning material
Unit-3 cyber security network security of internet system
INTERNET------BASICS-------UPDATED PPT PRESENTATION
Unit-1 introduction to cyber security discuss about how to secure a system
Introduction to Information and Communication Technology
Paper PDF World Game (s) Great Redesign.pdf
Tenda Login Guide: Access Your Router in 5 Easy Steps
presentation_pfe-universite-molay-seltan.pptx
innovation process that make everything different.pptx
Slides PPTX World Game (s) Eco Economic Epochs.pptx
FINAL CALL-6th International Conference on Networks & IOT (NeTIOT 2025)
Power Point - Lesson 3_2.pptx grad school presentation
Best Practices for Testing and Debugging Shopify Third-Party API Integrations...
artificialintelligenceai1-copy-210604123353.pptx
Sims 4 Historia para lo sims 4 para jugar
E -tech empowerment technologies PowerPoint
Slides PDF The World Game (s) Eco Economic Epochs.pdf
An introduction to the IFRS (ISSB) Stndards.pdf

cauldron-2022-docs-bof at gcc cauldron in 2022

  • 2. Copyright © SUSE 2022 2 Where do we have a documentation? 1) Web pages at gcc.gnu.org ● development info and releases (changes, porting to) ● git contribution (write access, development branches, ...) ● GNU coding style; git ChangeLog format ● open project info (C++ features, ...) 2)Texinfo documentation in git repository ● User-Level Documentation ● Internals Documentation 3)GCC WIKI at gcc.gnu.org/wiki ● Cauldron events ● List of historical and current projects ● internal documentation (LTO plug-in API, LTO offloading, ...)
  • 3. Copyright © SUSE 2022 3 What formats do we use? 1) Web pages at gcc.gnu.org ● input: HTML ● output: HTML 2)Texinfo documentation in git repository ● input: Texinfo ● output: manual pages, info, HTML and PDF 3)GCC wikipedia at gcc.gnu.org/wiki ● input: wiki markup ● output: HTML
  • 4. Copyright © SUSE 2022 4 Who are documentation stakeholders? 1)Users (consume) 2)Developers (produce) 3)Package maintainers, people who build toolchain (produce & consume)
  • 6. Copyright © SUSE 2022 6 Limitations of the current documentation ● Poor navigation (Next, Previous, Up, …) ● No search capability (Google is workaround) ● Poor formatting (font sizes, colours, spacing) ● Poor link anchors (maybe fixed in latest Texinfo) ● Almost no cross-references (definition vs. usage) ● Missing extra features (code snippet highlighting, cross references, link checking, …) ● Limited set of directives/keywords
  • 7. Copyright © SUSE 2022 7 Why moving to Sphinx? ● we can address the aforementioned limitations ● already being used (libgccjit, 3 Ada manuals) ● ReStructuredText (RST) is a lightweight markup language ● proved by many projects (Read the Docs, Python ecosystem, Linux kernel, ...)
  • 8. Copyright © SUSE 2022 8 Limitations of Sphinx documentation ● automatic conversion may contain errata ● individual page map 1:1 to source file (100s of .rst files) ● developers need to learn a new documentation format ● git blame would become harder (still possible) ● update_web_docs_git – needs to be ported ● Sphinx warnings (duplicate definitions, attributes, …) ● Downstream docs needs to be converted (Modula-2) ● Python stack needed for GCC package build
  • 9. Copyright © SUSE 2022 9 What extra will Sphinx bring us? ● Intersphinx extension – cross manual references ● Sphinx Themes – many options ● Pygments – Python syntax highlighter ● Linkcheck builder – verify all URLs ● EPUB builder ● Changes and Porting to are big candidates for migration ● Intersphinx extension – cross manual references ● Sphinx Themes – many options ● Pygments – Python syntax highlighter ● Linkcheck builder – verify all URLs ● EPUB builder ● Changes and Porting to are big candidates for migration
  • 10. Copyright © SUSE 2022 10 Conversion details ● makeinfo --xml is used ● texi2rst.py – conversion script visits XML file and converts to RST ● GitHub action runs texi2rst.py for GCC devel/sphinx branch ● Manual changes are merged to automatically converted docs ● post processing – GCC patch set
  • 11. Copyright © SUSE 2022 11 Conclusion ● Can I make the conversion? ● What will be the best timing? ● Questions?