Add subsubsection in docs.

Mathics3 / mathics-core

An open-source Mathematica. This repository contains the Python modules for WL Built-in functions, variables, core primitives, e.g. Symbol, a parser to create Expressions, and an evaluator to execute them.

https://mathics.org

Other

763 stars 44 forks source link

Add subsubsection in docs. #1030

Open rocky opened 6 months ago

rocky commented 6 months ago

Mathics3 modules in documentation are shifted down a level. In order to support "Guide" sections in Mathics3 modules, we would need to add a subsubsection support in LaTeX.

Consider https://reference.wolfram.com/language/guide/LinguisticData.html

linguistic-data

We currently can't capture this structure in our documents because WordTranslation, Alphabet, LanguageIdentify etc. are at the subsubsection level.

Because right now document structure follows module structure, we also can't create a module in the Mathics3 Module for "Languages and Translation" and "Textual Analysis" and have its appear in the LaTeX doc.

Two other things.

Having subsubsections might be also useful outside of Mathics3 Modules.

Note that in Wolfram documentation Symbols are at multiple levels: WordData is at a different level than WordTranslation. If you want to think of there being and "anonymous" section or subsection", note that there is more than one of these anonymous (sub)sections

mmatera commented 6 months ago

@rocky, actually, we still have "Subsections". What I have changed is that "GuideSections" are Sections, so they contain "Subsections" instead of sections. Symbols in pymathics.natlang.translation should be accommodated in the current "mathics-code/master" as Subsection of a GuideSection "Translation" inside the chapter "Natural Language" of the "Mathics Modules" Part.

I didn't check this package (I just had installed Pymathics.Graph when I run the tests) but it should work exactly the same. I will check what happens with natlang during the weekend.

mmatera commented 6 months ago

Regarding this:

We currently can't capture this structure in our documents because WordTranslation, Alphabet, LanguageIdentify etc. are at the subsubsection level.

These elements are shown different in the documentation because they are not considered "Built-in Symbols" but "Entities":

In the online documentation there are no chapters/sections/subsections: just different kind of webpages ("Built-in refereces", "Guide Sections", "Tutorials", and "Entities").

rocky commented 6 months ago

From a code organization standpoint, it would be good to start supporting a format like that used in https://github.com/Mathics3/pymathics-natlang/pull/19/files . What you want to call the levels of the hierarchy in the LaTeX doc is up for discussion. However in the LaTeX markup, the nesting level is "subsubsection."

mmatera commented 6 months ago

OK. My proposal for this would be to have three guides in the "Natural Language" chapter:

Linguistic Data: Include (as a documentation entry, an explanation of the content, and a list)
Languages & Translations: contains the symbols in lang_trans.py as subsections
Translation: contains the symbols in lang_trans.py as subsections.

rocky commented 6 months ago

OK. My proposal for this would be to have three guides in the "Natural Language" chapter:

Linguistic Data: Include (as a documentation entry, an explanation of the content, and a list)

Languages & Translations: contains the symbols in lang_trans.py as subsections

Translation: contains the symbols in lang_trans.py as subsections.

Yes, that makes sense. The problem of this issue/feature is that right now we can't extract docs for the lowest level.

mmatera commented 6 months ago

This is how Natlang looks (from its master branch) when I remove the other parts and chapters from documentation.tex:

During the weekend I will try to adjust this.