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.

Sign up for GitHub

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

Jump to bottom

Simple ReST renderer for CLI help texts #2574

Merged
merged 14 commits into from
Feb 6, 2024
Merged

Simple ReST renderer for CLI help texts #2574

merged 14 commits into from
Feb 6, 2024

Conversation

happz
Copy link
Collaborator

@happz happz commented Dec 15, 2023 •
edited
Loading

Plugin documentation lives in plugin docstrings and help texts of its
fields. It is rendered with Sphinx to create nice HTML docs, and using
ReST directives improves context, readability and interlinking of those
HTML docs. But for CLI, tmt does not have a ready-to-use ReST renderer,
which means on CLI, directives recognized by ReST and Sphinx are messy,
poorly visible and create unpleasant experience.

Patch adds a very trivial ReST renderer which is applied to plugin
docstrings and help texts of their fields. Uses colors and formats some
basic structures like lists or code-blocks.

Pull Request Checklist

  • implement the feature

Previews

https://tmt--2574.org.readthedocs.build/en/2574/plugins/index.html

2024-01-31_13-38

2024-01-31_13-40_1

2024-01-31_13-39

2024-01-31_13-40

@happz happz added the documentation Improvements or additions to documentation label Dec 15, 2023
@happz happz added this to the 1.31 milestone Dec 15, 2023
@happz happz mentioned this pull request Dec 15, 2023
Open
@happz happz force-pushed the rest-rendering-for-help branch 2 times, most recently from 7dd7c94 to f5b5538 Compare January 5, 2024 12:08
@happz happz changed the base branch from main to docs-plugins-from-template-and-sources January 5, 2024 12:08
@happz happz force-pushed the docs-plugins-from-template-and-sources branch 2 times, most recently from 044dbed to 2ffecd3 Compare January 15, 2024 20:31
@happz happz force-pushed the docs-plugins-from-template-and-sources branch from 2ffecd3 to e3282e0 Compare January 17, 2024 08:25
@happz happz force-pushed the rest-rendering-for-help branch 2 times, most recently from 000dd0f to fc1b487 Compare January 18, 2024 12:36
@happz happz added the status | blocked The merging of PR is blocked on some other issue label Jan 23, 2024
@happz happz force-pushed the docs-plugins-from-template-and-sources branch from a551f2e to a2933ec Compare January 23, 2024 09:29
@happz happz force-pushed the docs-plugins-from-template-and-sources branch from a2933ec to 8d2ef47 Compare January 26, 2024 08:36
@happz happz force-pushed the docs-plugins-from-template-and-sources branch from 8d2ef47 to 1dc5dc9 Compare January 29, 2024 13:16
@happz happz force-pushed the docs-plugins-from-template-and-sources branch from 1dc5dc9 to 93eceec Compare January 31, 2024 11:28
@happz happz changed the title Rest rendering for help Simple ReST renderer for CLI help texts Jan 31, 2024
@happz
Copy link
Collaborator Author

happz commented Jan 31, 2024

/packit test -i full

@happz happz force-pushed the docs-plugins-from-template-and-sources branch from 93eceec to b197b2e Compare February 2, 2024 14:15
@happz happz marked this pull request as ready for review February 2, 2024 14:19
@happz
Simple ReST renderer for CLI help texts
65061cd 
Plugin documentation lives in plugin docstrings and elp texts of its
fields. It is rendered with Sphinx to create nice HTML docs, and using
ReST directives improves context, readability and interlinking of those
HTML docs. But for CLI, tmt does not have a ready-to-use ReST renderer,
which means on CLI, directives recognized by ReST and Sphinx are messy,
poorly visible and create unpleasant experience.

Patch adds a very trivial ReST renderer which is applied to plugin
docstrings and help texts of their fields. Uses colors and formats some
basic structures like lists or `code-block`s.
@happz
squash: few tweaks
04e8450
@happz
squash: fix wrong make target
4a1fec4
@happz
squash improvements
c46edfd
@happz
squash: more improvements
1392920
@happz
squash: convert test checks to plugins
5e2e672
@happz
squash: improve documentation
d689c2a
@happz
squash: add pygments
b8d27be
@happz
squash: fix features docstring
8ca0241
@psss
squash: A couple of minor changes
f381882 
Fix `Common Keys` heading to be on the same level.
Proposing note/warning colors consistent with the web.
Plus some minor chanes.
psss
psss approved these changes Feb 5, 2024
View reviewed changes
Copy link
Collaborator

@psss psss left a comment

Choose a reason for hiding this comment

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

Thanks, looks very nice! Could we perhaps keep colors for the notes and warnings consistent with how they are shown on the web? Proposing in f381882 together with a couple of minor changes.

@psss
Copy link
Collaborator

psss commented Feb 5, 2024

Two more things I've noticed: Seems that bullet points inside notes have an extra NOTE tag included in the text:

NOTE: When testing ostree booted deployments tmt will use
rpm-ostree as the package manager to perform the installation of
requested packages. The current limitations of the rpm-ostree
implementation are:

* NOTE: Cannot install new version of already installed local rpm.
* NOTE: No support for installing debuginfo packages at this time.

The tests field of the discover.shell plugin is missing a description.

@psss psss removed the status | blocked The merging of PR is blocked on some other issue label Feb 5, 2024
@happz
Copy link
Collaborator Author

happz commented Feb 5, 2024

Thanks, looks very nice! Could we perhaps keep colors for the notes and warnings consistent with how they are shown on the web? Proposing in f381882 together with a couple of minor changes.

Added a reply in f381882#r138267199, the rest of changes look good to me.

@happz
Copy link
Collaborator Author

happz commented Feb 5, 2024

Two more things I've noticed: Seems that bullet points inside notes have an extra NOTE tag included in the text:

NOTE: When testing ostree booted deployments tmt will use
rpm-ostree as the package manager to perform the installation of
requested packages. The current limitations of the rpm-ostree
implementation are:

* NOTE: Cannot install new version of already installed local rpm.
* NOTE: No support for installing debuginfo packages at this time.

Hopefully addressed in 2ee42e1

The tests field of the discover.shell plugin is missing a description.

True, and I would probably leave it for the later PR since the whole plugin docs require a review, and tests is just a drop.

thrix
thrix approved these changes Feb 5, 2024
View reviewed changes
Copy link
Collaborator

@thrix thrix left a comment

Choose a reason for hiding this comment

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

lgtm, small suggestion

tmt/steps/report/junit.py Outdated Show resolved Hide resolved
@happz @thrix
squash: Update tmt/steps/report/junit.py
e1a45dd 
Co-authored-by: Miroslav Vadkerti <mvadkert@redhat.com>
@lukaszachy
Copy link
Collaborator

/packit test -i full

happz
happz commented Feb 5, 2024
View reviewed changes
docs/templates/plugins.rst.j2 Outdated Show resolved Hide resolved
@happz
Copy link
Collaborator Author

happz commented Feb 5, 2024

/packit test -i full

@happz
Copy link
Collaborator Author

happz commented Feb 5, 2024

/packit test -i full

@happz
Copy link
Collaborator Author

happz commented Feb 5, 2024

/packit test -i provision

@happz happz merged commit 97b84ca into main Feb 6, 2024
19 checks passed
@happz happz deleted the rest-rendering-for-help branch February 6, 2024 09:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@thrix thrix thrix approved these changes

@lukaszachy lukaszachy lukaszachy approved these changes

@psss psss psss approved these changes

@janhavlin janhavlin janhavlin approved these changes

@KwisatzHaderach KwisatzHaderach Awaiting requested review from KwisatzHaderach KwisatzHaderach is a code owner

@dav-pascual dav-pascual Awaiting requested review from dav-pascual dav-pascual is a code owner

@frantisekz frantisekz Awaiting requested review from frantisekz frantisekz is a code owner

@martinhoyer martinhoyer Awaiting requested review from martinhoyer martinhoyer is a code owner

Assignees
No one assigned
Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
1.31
Development

Successfully merging this pull request may close these issues.
5 participants
@happz @psss @lukaszachy @thrix @janhavlin