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] Minor tweak to md sanitisation code #20735

Merged
merged 1 commit into from
Jan 7, 2024

Conversation

rswarbrick
Copy link
Contributor

@rswarbrick rswarbrick commented Dec 24, 2023

This code replaces \n with a space when populating table cells. A good
idea! But it ended up leaving a double space if the source hjson had a
blank line.

There was also a bit of a mess if we have a newline followed by several
spaces. This turned into two spaces, not one.

The fix is simple: treat any number of newlines, followed by any
number of spaces as a single space. The handwritten code here is just
a 1-line change to md_helpers.py. The rest of the commit is from
regenerating the auto-generated stuff that it builds.

Note that this was annoying to create because we check in the
auto-generated registers.md for pwrmgr in a template file (presumably
manually) and then use that auto-generated file to create the
registers.md in ip_autogen. We should probably stop doing that silly
thing at some point, but my local hack was to apply the fix to the
markdown files with

util/cmdgen.py -u '**/*.md'

and then manually copy the changed lines to the template file before
re-running

make -C hw top

This works, but... yuck!

@rswarbrick rswarbrick added Component:Doc Documentation issue Type:Cleanup Cleanup tasks labels Dec 24, 2023
@rswarbrick rswarbrick requested a review from HU90m December 24, 2023 16:54
@rswarbrick
Copy link
Contributor Author

rswarbrick commented Dec 24, 2023

This fixes one of the two things I found for a single IP and hackily semi-fixed in #20734. This attempt should be a bit more sensible.

EDIT: Actually, it fixes both! They both turned out to be the same problem, now sorted.

@rswarbrick rswarbrick force-pushed the md-sanitation-blank-lines branch 4 times, most recently from bdf513f to e7ad3ec Compare December 25, 2023 17:21
This code replaces \n with a space when populating table cells. A good
idea! But it ended up leaving a double space if the source hjson had a
blank line.

There was also a bit of a mess if we have a newline followed by several
spaces. This turned into two spaces, not one.

The fix is simple: treat any number of newlines, followed by any
number of spaces as a single space. The handwritten code here is just
a 1-line change to md_helpers.py. The rest of the commit is from
regenerating the auto-generated stuff that it builds.

Note that this was annoying to create because we check in the
auto-generated registers.md for pwrmgr in a template file (presumably
manually) and then use that auto-generated file to create the
registers.md in ip_autogen. We should probably stop doing that silly
thing at some point, but my local hack was to apply the fix to the
markdown files with

    util/cmdgen.py -u '**/*.md'

and then manually copy the changed lines to the template file before
re-running

    make -C hw top

This works, but... yuck!

Signed-off-by: Rupert Swarbrick <[email protected]>
@rswarbrick rswarbrick force-pushed the md-sanitation-blank-lines branch from e7ad3ec to fa17526 Compare December 26, 2023 16:52
@rswarbrick
Copy link
Contributor Author

Oof, this was painful to get right. The problem is that we automatically generated some Markdown that we then renamed to hw/ip_templates/pwrmgr/doc/registers.md.tpl and then checked in (see commit 8034e00). This doesn't get automatically updated with the automatic cmdgen script, and running that script manually on the tpl file also doesn't work.

Grr, what a bodge! Anyway, fixing things manually seems to get things sorted again for now.

Copy link
Contributor

@matutem matutem left a comment

Choose a reason for hiding this comment

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

Seems good. I trust you build the docs and did some perusing of the affected files.

@rswarbrick rswarbrick merged commit 963a500 into lowRISC:master Jan 7, 2024
32 checks passed
@rswarbrick rswarbrick deleted the md-sanitation-blank-lines branch January 7, 2024 21:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Component:Doc Documentation issue Type:Cleanup Cleanup tasks
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants