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

DOC: Generate the charset tables dynamically from codes #3409

Merged
merged 9 commits into from
Sep 1, 2024
Merged

Conversation

seisman
Copy link
Member

@seisman seisman commented Aug 22, 2024

Description of proposed changes

After adding the myst-nb extension in #3379, it's possible to generate the charset tables dynamically from codes.

Preview:

Pros:

  1. No need to maintain the charset tables manually
  2. Make sure that the documentation is consistent with the codes

Cons:

  1. Maybe a little slower in building the documentation [Building docs takes the same time (105 seconds) on the main branch and this PR, so the changes in this PR has negligible effects].
  2. ruff can't format the codes in Markdown ☂️ Formatter: Support formatting of embedded code astral-sh/ruff#8237, so we need to format the codes manually.

@seisman seisman added documentation Improvements or additions to documentation maintenance Boring but important stuff for the core devs skip-changelog Skip adding Pull Request to changelog needs review This PR has higher priority and needs review. labels Aug 22, 2024
@seisman seisman added this to the 0.13.0 milestone Aug 22, 2024
from pygmt.encodings import charset


def get_charset_mdtable(name):
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This function is modified from the original script at #3206 (comment)

@seisman seisman changed the title DOC: Generate the charset tables dynamically in the documentation DOC: Generate the charset tables dynamically from codes Aug 22, 2024
@seisman seisman removed the needs review This PR has higher priority and needs review. label Aug 22, 2024
@seisman seisman marked this pull request as draft August 22, 2024 16:36
@seisman seisman marked this pull request as ready for review August 23, 2024 06:41
doc/conf.py Outdated
Comment on lines 64 to 66
# MyST-NB configurations: https://myst-nb.readthedocs.io/en/latest/configuration.html
nb_render_markdown_format = "myst" # The format to use for text/markdown rendering

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The default value is 'commonmark', which doesn't support tables.

@@ -203,3 +203,19 @@ a.copybtn {
.sphx-glr-single-img {
max-width: 80%!important;
}

/*
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here is the CSS styles from myst-nb.

div.cell_output tr,
div.cell_output th,
div.cell_output td {
  text-align: right;
  vertical-align: middle;
  padding: 0.5em 0.5em;
  line-height: normal;
  white-space: normal;
  max-width: none;
  border: none;
}

The text-align is set to right, which makes sense for displaying objects like pandas.DataFrame (an example at https://myst-nb.readthedocs.io/en/latest/render/format_code_cells.html#remove-stdout-or-stderr).

In MyST, the table cell alignment can be controlled using : characters (https://myst-parser.readthedocs.io/en/latest/syntax/tables.html), which is done by assigning text-left/text-center/text-right to cells. These CSS classes are not defined in Sphinx_rtd_theme, so we have to define them here.

@seisman seisman added the needs review This PR has higher priority and needs review. label Aug 23, 2024
@michaelgrund michaelgrund added final review call This PR requires final review and approval from a second reviewer and removed needs review This PR has higher priority and needs review. labels Aug 28, 2024
@seisman seisman merged commit c54d72f into main Sep 1, 2024
10 checks passed
@seisman seisman deleted the doc/encodings branch September 1, 2024 09:40
@seisman seisman removed the final review call This PR requires final review and approval from a second reviewer label Sep 1, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation maintenance Boring but important stuff for the core devs skip-changelog Skip adding Pull Request to changelog
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants