Copy of Sphinx talk

Get Started. It's Free
or sign up with your email address
Rocket clouds
Copy of Sphinx talk by Mind Map: Copy of Sphinx talk

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. Infra

11.1. reStructuredText

11.1.1. rst

11.1.2. Can use many characters for header levels, as long as its consistent

11.1.3. Simple lists & links

11.1.4. Admonitions

11.1.4.1. Borders & labels

11.1.5. Indentation like Python

11.1.6. But rst has no context across files

11.1.7. Extensible, via directives

11.1.7.1. TOC

11.2. PyGments

11.2.1. Used also in GitHub

11.3. Jinja2

12. Documentation is required & crucial

12.1. Affects adoption

12.2. DocStrings are not documentation

12.2.1. Arch, usage, philosophy

12.3. An important reject reason for commits is:

12.3.1. Need better docs

13. Quick start

13.1. sphinx-QuickStart <folder>

13.1.1. Asks you many questions

13.2. make HTML

14. Not just for Python

15. Extensions

15.1. eg,

15.1.1. Adds link to source code, whenever you refer to some function &c

15.1.2. autodoc

15.1.2.1. Documentation from DocStrings

15.1.2.2. automodule

15.1.2.3. autoclass

15.1.3. Rss

15.1.4. YouTube

15.1.5. Google Analytics

15.2. Sphinx Contrib

15.3. New Node

16. Themes

17. conf.py

17.1. Configuration file

17.1.1. Regular python file

17.1.1.1. Eg, inc version number

17.1.2. Add extensions

17.1.3. Sphinx needs this to understand the structure & global metadata of your project

17.1.4. Like settings.py

18. TOC

18.1. Auto generated

18.2. Toc directivr

18.3. Define max depth

19. Labels

19.1. Used for cross references

19.1.1. _coolproj:

19.1.2. For more info: :ref: coolproj

20. Indexing

20.1. Auto generated

20.1.1. Index directive

20.1.1.1. Index:

20.1.1.2. single: Executive Example

20.1.1.3. single: User Guide; Execution Example

21. Domains

21.1. Python domain

21.1.1. To label code elements

21.1.1.1. py:function:: format_exception

21.1.1.2. :param etype exception type

21.1.1.2.1. If you put this in DocString it will understand what you are describing

21.1.1.3. For more info see :py:func: format_exception

21.2. Many more domains

22. ReadTheDocs

22.1. Auto updating

22.1.1. All VCS & many code hosting sites

22.2. Caching

22.3. Versions

22.4. PDF generation

22.5. Search

22.5.1. JS

22.5.2. FTS

22.6. Alternate domains

22.6.1. awesome.readthedocs.org

22.7. Intersphinx

22.7.1. Cross references between projects

22.7.1.1. Soft logical links

23. Meir use it for Presentations

24. Tip

24.1. python -m http.server

24.1.1. Web server in current dir

24.2. python -m SimpleHttpServer