Skip to content

Conversation

kwankyu
Copy link
Collaborator

@kwankyu kwankyu commented Jun 16, 2023

📚 Description

(1) Implement persistent optional tags for block-scoped optional tags
(2) Add "needs" as an alternative to "optional"

Thus doctests can be written as

            sage: # needs sage.rings.number_field, long time
            sage: QQbar(I)^10000
            1
            sage: QQbar(I)^10000  # not tested
            I
            sage: # needs sage.rings.finite_rings
            sage: GF(7)
            Finite Field of size 7
            sage: GF(10)
            Traceback (most recent call last):
            ...
            ValueError: the order of a finite field must be a prime power

Resolves #35750.

📝 Checklist

  • The title is concise, informative, and self-explanatory.
  • The description explains in detail what this PR is about.
  • I have linked a relevant issue or discussion.
  • I have created tests covering the changes.
  • I have updated the documentation accordingly.

⌛ Dependencies

@github-actions
Copy link

Documentation preview for this PR (built with commit bdc4232) is ready! 🎉

@mkoeppe
Copy link
Contributor

mkoeppe commented Jun 17, 2023

The implementation looks clean, but I'll leave it to participants of the discussion in #35750 to set it to positive review.

@kwankyu
Copy link
Collaborator Author

kwankyu commented Jun 17, 2023

The implementation looks clean, but I'll leave it to participants of the discussion in #35750 to set it to positive review.

Thanks. That is fair.

@mkoeppe
Copy link
Contributor

mkoeppe commented Jun 29, 2023

I've merged it in #35749, where I have made a few refinements. Works well.

@kwankyu
Copy link
Collaborator Author

kwankyu commented Jun 30, 2023

OK.

@kwankyu
Copy link
Collaborator Author

kwankyu commented Jul 5, 2023

The branch of this PR has conflicts with the develop branch. Instead of fixing them, I can close this PR as #35749 has merged the branch. OK?

@mkoeppe
Copy link
Contributor

mkoeppe commented Jul 5, 2023

OK.

@kwankyu kwankyu closed this Jul 5, 2023
@kwankyu kwankyu deleted the persistent-optional-tags branch July 5, 2023 01:42
vbraun pushed a commit that referenced this pull request Jul 30, 2023
gh-35749: Add style guide / reference for `# optional - sage....` doctest tags, extend `sage -t` and `sage -fixdoctests` for modularization tasks
    
<!-- Please provide a concise, informative and self-explanatory title.
-->
<!-- Don't put issue numbers in the title. Put it in the Description
below. -->
<!-- For example, instead of "Fixes #12345", use "Add a new method to
multiply two integers" -->

### 📚 Description

<!-- Describe your changes here in detail. -->
- Fixing the handling of file-level `# optional` tags.
- Some files were not being doctested; fixing the recently introduced
errors in doctests.
- Implementing block-scoped tags (originally done in PR #35779, merged
here)
- Expanding the documentation on the `# optional` / `# needs` tags used
for modularization purposes, with examples.
- Adding features `sage.modular`, `sage.numerical.mip`,
`sage.rings.complex_double`, `sage.sat`
- The tools `sage -t` and `sage --fixdoctests` receive some new options
for modularization tasks (see added documentation):
   ```
   $ make pypi-wheels
   $ make SAGE_CHECK=yes sagemath-modules
   $ ./sage --fixdoctests --distribution sagemath-modules \
src/sage/combinat/root_system/root_lattice_realization_algebras.py
   ```
   (example uses #35095)
- Suppressing `# optional`/`# needs` of present features in the help
system
.

<!-- Why is this change required? What problem does it solve? -->
Motivated by the sage-devel thread https://groups.google.com/g/sage-
devel/c/utA0N1it0Eo (2023-06)

<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes #12345". -->
- Resolves #35790
- Resolves #35750
- Part of #29705
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. It should be `[x]` not `[x
]`. -->

- [x] The title is concise, informative, and self-explanatory.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [x] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- #12345: short description why this is a dependency
- #34567: ...
-->
- Depends on #35820 (merged here)
- Vote at https://groups.google.com/g/sage-devel/c/8KZNRBs6F6U (result:
https://groups.google.com/g/sage-devel/c/MtS2u3VbJEo)
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: #35749
Reported by: Matthias Köppe
Reviewer(s): Kwankyu Lee, Matthias Köppe
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Codeblock-scoped # optional annotations for doctests (modularization)
2 participants