search

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
733 stars 42 forks source link

Doc code rebased rebased #999

Closed rocky closed 4 months ago

rocky commented 4 months ago

Things we need to do to get #984 functionality for the current master.

A bit of code has been DRY'd.

rocky commented 4 months ago

Here is what remains...

However since this PR is a bit large, perhaps we should commit as is and iterate the above in a new PR? @mmatera - your thoughts?

One thing that is cool is that we can quickly create documentation narrowed to a particular Part name. In other words, MATHICS_CHARACTER_ENCODING="ASCII" SANDBOX= python3 doc2latex.py -p 'Manual' works. Down the line, section filtering, or the -s option, might be gone over too.

We still need to create a discussion for the various documentation things to do and possibly a plan for that.

mmatera commented 4 months ago

Here is what remains...

* `make doctest-data` fails all of the Mathics3 Module tests. I imagine somewhere, somehow the definitions it adds get removed.  Note that when this is run in isolation such as by `MATHICS_CHARACTER_ENCODING="ASCII" SANDBOX= python3 mathics/docpipeline.py --load-module pymathics.graph,pymathics.natlang -s 'Core routines for working with Graphs.'` everything works.

* more unit tests for the doctest options, `mathics.doc.util` and `mathics.doc.common_doc` should be written.

* Guide Section names names in Mathics3 Modules appears twice in the LaTeX documentation and should be removed.

* We should allow Guide sections to appear in Mathics3 Modules

OK, let's merge this and iterate. However, I though that in my branch the doctests for graphs works, and guide sections worked both in in the main and the modules section.

However since this PR is a bit large, perhaps we should commit as is and iterate the above in a new PR? @mmatera - your thoughts?

What about trying to split this into smaller PRs? There are changes in the documentation of some builtins that should work in master as it is. Also, the part of moving some functions to the mathics.doc.utils could be done with too much work.

One thing that is cool is that we can quickly create documentation narrowed to a particular Part name. In other words, MATHICS_CHARACTER_ENCODING="ASCII" SANDBOX= python3 doc2latex.py -p 'Manual' works. Down the line, section filtering, or the -s option, might be gone over too.

That is indeed cool. What we maybe should change is to use "section" when what we mean is builtin symbol: In GuideSections, Builtin symbols appears as "subsections".

We still need to create a discussion for the various documentation things to do and possibly a plan for that.

I fully agree. I guess that in this round of revision, we learned several things about the documentation system, and several new ideas of improvement came up.

rocky commented 4 months ago

However, I though that in my branch the doctests for graphs works, and guide sections worked both in in the main and the modules section.

And it also worked in the first PR before that. I suspect this is small bug somewhere in further refactoring. It is possible in the fixing of this we can get things clearer and better. But I think that kind of thing is better done in isolation from this code.

What about trying to split this into smaller PRs?

Good. I will look over all of the changes to see what can be split off. There are some basic bug fixes that I know can be isolated.

Which reminds me, we still have #997 hanging out there.