1. Indexing
1.1. Auto generated
1.1.1. Index directive
1.1.1.1. Index:
1.1.1.2. single: Executive Example
1.1.1.3. single: User Guide; Execution Example
2. Labels
2.1. Used for cross references
2.1.1. _coolproj:
2.1.2. For more info: :ref: coolproj
3. TOC
3.1. Auto generated
3.2. Toc directivr
3.3. Define max depth
4. conf.py
4.1. Configuration file
4.1.1. Regular python file
4.1.1.1. Eg, inc version number
4.1.2. Add extensions
4.1.3. Sphinx needs this to understand the structure & global metadata of your project
4.1.4. Like settings.py
5. Themes
6. Extensions
6.1. eg,
6.1.1. Adds link to source code, whenever you refer to some function &c
6.1.2. autodoc
6.1.3. Rss
7. Not just for Python
8. Quick start
8.1. sphinx-QuickStart
8.1.1. Asks you many questions
8.2. make HTML
9. Documentation is required & crucial
9.1. Affects adoption
9.2. DocStrings are not documentation
9.2.1. Arch, usage, philosophy
9.3. An important reject reason for commits is:
9.3.1. Need better docs
10. Infra
10.1. reStructuredText
10.1.1. rst
10.1.2. Can use many characters for header levels, as long as its consistent
10.1.3. Simple lists & links
10.1.4. Admonitions
10.1.4.1. Borders & labels
10.1.5. Indentation like Python
10.1.6. But rst has no context across files
10.1.7. Extensible, via directives
10.1.7.1. TOC
10.2. PyGments
10.2.1. Used also in GitHub
10.3. Jinja2
11. Documentation is required & crucial
11.1. Affects adoption
11.2. DocStrings are not documentation
11.2.1. Arch, usage, philosophy
11.3. An important reject reason for commits is:
11.3.1. Need better docs
12. Tip
12.1. python -m http.server
12.1.1. Web server in current dir
12.2. python -m SimpleHttpServer
13. Infra
13.1. reStructuredText
13.1.1. rst
13.1.2. Can use many characters for header levels, as long as its consistent
13.1.3. Simple lists & links
13.1.4. Admonitions
13.1.4.1. Borders & labels
13.1.5. Indentation like Python
13.1.6. But rst has no context across files
13.1.7. Extensible, via directives
13.1.7.1. TOC
13.2. PyGments
13.2.1. Used also in GitHub
13.3. Jinja2
14. Quick start
14.1. sphinx-QuickStart <folder>
14.1.1. Asks you many questions
14.2. make HTML
15. Not just for Python
16. Extensions
16.1. eg,
16.1.1. Adds link to source code, whenever you refer to some function &c
16.1.2. autodoc
16.1.2.1. Documentation from DocStrings
16.1.2.2. automodule
16.1.2.3. autoclass
16.1.3. Rss
16.1.4. YouTube
16.1.5. Google Analytics
16.2. Sphinx Contrib
16.3. New Node
17. Themes
18. conf.py
18.1. Configuration file
18.1.1. Regular python file
18.1.1.1. Eg, inc version number
18.1.2. Add extensions
18.1.3. Sphinx needs this to understand the structure & global metadata of your project
18.1.4. Like settings.py
19. TOC
19.1. Auto generated
19.2. Toc directivr
19.3. Define max depth
20. Labels
20.1. Used for cross references
20.1.1. _coolproj:
20.1.2. For more info: :ref: coolproj
21. Indexing
21.1. Auto generated
21.1.1. Index directive
21.1.1.1. Index:
21.1.1.2. single: Executive Example
21.1.1.3. single: User Guide; Execution Example
22. Domains
22.1. Python domain
22.1.1. To label code elements
22.1.1.1. py:function:: format_exception
22.1.1.2. :param etype exception type
22.1.1.2.1. If you put this in DocString it will understand what you are describing
22.1.1.3. For more info see :py:func: format_exception
22.2. Many more domains
23. ReadTheDocs
23.1. Auto updating
23.1.1. All VCS & many code hosting sites
23.2. Caching
23.3. Versions
23.4. PDF generation
23.5. Search
23.5.1. JS
23.5.2. FTS
23.6. Alternate domains
23.6.1. awesome.readthedocs.org
23.7. Intersphinx
23.7.1. Cross references between projects
23.7.1.1. Soft logical links