new documentation categories "FAQ" and "Thematic Tutorials"

[sagetrac-mvngu]

This is a meta-ticket that helps in organizing changes and additions to the Sage standard documentation. On sage-devel and sage-combinat-devel, it is proposed that we create two new documentation categories called:

• FAQ --- a collection of answers to frequently asked questions.
• Thematic Tutorials --- a collection of in-depth tutorials on specific topics.

See this thread on sage-devel for further discussion about more accessible documentation. For starters, here is a list of tickets with enhancements for those two new documentation categories:

• Lie Methods and Related Combinatorics (tutorial) #8442 Lie Methods and Related Combinatorics
• add FAQ to standard documentation #8464 FAQ
• move the document "Python Functional Programming for Mathematicians" to the classification "Thematic Tutorials" #8465 Python Functional Programming for Mathematicians
• include the document "Sage and Coding Theory" in the classification "Thematic Tutorials" #8466 Sage and Coding Theory
• move the document "Linear Programming in Sage" to "Thematic Tutorials" #8467 Linear Programming in Sage
• add "Group Theory and Sage: A Primer" to the classification "Thematic Tutorials" #8468 Group Theory and Sage: A Primer
• add "Number Theory and the RSA Public Key Cryptosystem" to "Thematic Tutorials" #8469 Number Theory and the RSA Public Key Cryptosystem
• tutorial on Python object and classes #8886 tutorial on Python object and classes

Once all the above tickets are closed, the current ticket can be closed as fixed.

Prerequisites:

1. stylistic clean-ups on web page of standard documentation #8480 stylistic clean-ups on web page of standard documentation
2. add "Group Theory and Sage: A Primer" to the classification "Thematic Tutorials" #8468 Group Theory and Sage
3. add FAQ to standard documentation #8464 add FAQ to standard documentation
4. browse thematic tutorials from command line and within notebook #8533 browse thematic tutorials from command line and within notebook
5. move the document "Python Functional Programming for Mathematicians" to the classification "Thematic Tutorials" #8465 Functional Programming for Mathematicians
6. add "Number Theory and the RSA Public Key Cryptosystem" to "Thematic Tutorials" #8469 Number Theory and the RSA Public Key Cryptosystem
7. Lie Methods and Related Combinatorics (tutorial) #8442 Lie Methods and Related Combinatorics

CC: @wdjoyner @rlmill @nathanncohen @rbeezer @sagetrac-sage-combinat @dwbump @jhpalmieri @jasongrout

Component: documentation

Keywords: FAQ, HOWTO, tutorial

Reviewer: Ralf Stephan, Karl-Dieter Crisman

Issue created by migration from https://trac.sagemath.org/ticket/8470

[nthiery]

comment:3

This sounds very good! Should the following appear there as well?

• the category primer (sage.categories.primer)
• the "implementing a parent" tutorial (sage.categories.tutorial); this needs further work!

For the record, in the Sage-Combinat queue, some work is being done on:

• A tutorial on iterators
• A tutorial on combinatorics

[sagetrac-mvngu]

Changed keywords from FAQ, HOWTO to FAQ, HOWTO, tutorial

[dwbump]

comment:11

Here is a more complete list of patches that are relevant
to this metaticket:

trac_8480-clean-up.patch
trac_8464-faq-general.patch
trac_8464-faq-usage.patch
trac_8464-faq-contribute.patch
trac_8464-ref.patch
trac_8465-functional.patch
trac_8469-rsa.patch
trac_8468-groups.patch
trac_8411_branching_rules.patch
trac_8414_weyl_group_space.patch
trac_8442-lie-rebased.patch
trac_8442-reviewer.patch
trac_8492-ref.patch

In addition three .png files from #8442 need to be copied into
doc/en/thematic_tutorials/static.

With this preparation, the pdf and html documentation build and look very good.

[rwst]

comment:19

All done!

[kcrisman]

comment:20

We certainly need better organization of documentation, but this ticket has achieved its purpose, you are right. Too bad #8533 isn't finished yet, but oh well.

[kcrisman]

Reviewer: Ralf Stephan, Karl-Dieter Crisman