Doc code revision rebased

[mmatera]

This PR collects all the changes that I found are needed to make #984 work, in the sense of generating all the doctests, producing the pdf documentation, and playing well with Mathics-Django.

[mmatera]

This PR contains the changes (including some tweaks I elaborated in #993) to make #984 work. After merging this, I think that still, we still need to do some extra cleaning and reordering to make the code more readable and free of dead branches.

Also, I see that mathics.doc.common module is too large. I distinguish three different things inside it that could be put in different submodules:

• The structural class hierarchy (Documentation->DocPart->DocChapter->DocSection/DocGuide->DocSubsection->DocumentationEntry)
• The DocTest elements and their collections (DocTests and Tests).
• The mechanisms to gather the Documentation from the Python libraries.

But in any case, it is work for a subsequent step.

[rocky]

This PR contains the changes (including some tweaks I elaborated in #993) to make #984 work. After merging this, I think that still, we still need to do some extra cleaning and reordering to make the code more readable and free of dead branches.

Also, I see that mathics.doc.common module is too large. I distinguish three different things inside it that could be put in different submodules:

• The structural class hierarchy (Documentation->DocPart->DocChapter->DocSection/DocGuide->DocSubsection->DocumentationEntry)
• The DocTest elements and their collections (DocTests and Tests).
• The mechanisms to gather the Documentation from the Python libraries.

But in any case, it is work for a subsequent step.

Yes, please I would like to see more work on getting the problems that motivated this fixed.

With these changes, are we able to create Guide sections in Mathics3 modules now?

[mmatera]

@rocky with this changes the Guide sections seem to work in the PDF documentation (at least for pymathics.graph) and together with mathics-django/#201 it also produces the online documentation.

Still, there are some small details, like that in the online documentation, after loading a module, it is needed to press F5 to see the changes in the documentation, and that in the PDF documentation, sections out of a GuideSection look a little bit different. In any case, there are things that we can fix after this main part is completed.

[mmatera]

This is an example about how does it looks the pymathics.graph documentation in the PDF file:

and in the different levels of the online docs

[rocky]

This is an example about how does it looks the pymathics.graph documentation in the PDF file:

and in the different levels of the online docs

I'll look at everything within a day or two. The screenshot above lists "Centralities" 3 times. Here is what "mathicsdoc" currently shows. (It too lists "Centralities" multiple times).

[mmatera]

I'll look at everything within a day or two.

Good. I will not be able to work too much on this until de weekend.

The screenshot above lists "Centralities" 3 times. Here is what "mathicsdoc" currently shows. (It too lists "Centralities" multiple times).

Not sure what you mean. In the screenshot I just see a repetition in the url part. In any case , I think it will take one or two more rounds to be get this ready.

[rocky]

Superceded by other commits.