Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improving support for Markdown syntaxis in documentation entries. #1026

Open
wants to merge 31 commits into
base: master
Choose a base branch
from

Conversation

mmatera
Copy link
Contributor

@mmatera mmatera commented Mar 25, 2024

Adding support for markdown notation in figures and references. This would be helpful for a future migration to more standard documentation systems.

* Fix references in ImportExport
* Makes key generation more deterministic
* Fix typos in docstrings and comments
* Add the new versions of test_* in mathics.docpipeline, and keep the old ones
  when the new ones fail.
* Make more deterministic the key generation for ``DocTest``
* DRY __init__ methods in classes inside  latex_doc.py
* Fix references in ImportExport
* Makes key generation more deterministic
* Fix typos in docstrings and comments
* Add the new versions of test_* in mathics.docpipeline, and keep the old ones
  when the new ones fail.
* Make more deterministic the key generation for ``DocTest``
* DRY __init__ methods in classes inside  latex_doc.py
removing trailing code
…would be helpful for a future migration to

more standard documentation systems.
@rocky
Copy link
Member

rocky commented Mar 25, 2024

Personally, I think markdown at this stage is a bad idea. Sphinx works best with RsT. ad

Also, the regexps to handle this were kind of the wrong way to deal with documentation. Overall I'd like to reduce their use rather than increase their use and add more complexity here.

@mmatera
Copy link
Contributor Author

mmatera commented Mar 25, 2024

Ok, I could add the rules for the RST syntax in another branch.

@mmatera
Copy link
Contributor Author

mmatera commented Mar 25, 2024

Regarding the implementation, I see this as an intermediate step. This is why I tried to split the parts of the documentation system as much as possible.

The long term plan would be

  • support the most suitable syntax for using an existing documentation library
  • Progressively replace the old syntax by the new one.
  • Once the documentation can be handled by a standard parser, remove the homebrew, regex based parser.

* Fix references in ImportExport
* Makes key generation more deterministic
* Fix typos in docstrings and comments
* Add the new versions of test_* in mathics.docpipeline, and keep the old ones
  when the new ones fail.
* Make more deterministic the key generation for ``DocTest``
* DRY __init__ methods in classes inside  latex_doc.py
This PR is another version of #1025, which produces a documentation with
the same format as in the 6.0.4 documentation.
Base automatically changed from more_docpipeline_fixes to master April 3, 2024 21:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants