docs: improve handling of ResourceItem descriptions#1761
Merged
BareosBot merged 6 commits intobareos:masterfrom Apr 10, 2024
Merged
docs: improve handling of ResourceItem descriptions#1761BareosBot merged 6 commits intobareos:masterfrom
BareosBot merged 6 commits intobareos:masterfrom
Conversation
f3372f1 to
25b1d62
Compare
sebsura
reviewed
Apr 8, 2024
docs/manuals/source/DocumentationStyleGuide/BareosSpecificFormatting/BareosConfiguration.rst
Outdated
Show resolved
Hide resolved
bruno-at-bareos
requested changes
Apr 8, 2024
Contributor
There was a problem hiding this comment.
Nicely done, now to be able to build the PR,
@sebsura do you want to fix the extra openssl command we have in the C code
sphinx-build -M html ../b-at-bareos/docs/manuals/source docs/BareosMainReference -j16
Running Sphinx v5.3.0
/bareos/git/b-at-bareos/docs/manuals
INFO generate-resource-descriptions.createSphinx: Create RST/Sphinx files ...
INFO generate-resource-descriptions.__init__: format-version: 2
INFO generate-resource-descriptions.createSphinx: daemon: bareos-dir, resource: Catalog
INFO generate-resource-descriptions.createSphinx: daemon: bareos-dir, resource: Client
Traceback (most recent call last):
File "scripts/generate-resource-descriptions.py", line 507, in <module>
createSphinx(data)
File "scripts/generate-resource-descriptions.py", line 455, in createSphinx
sphinx.writeResourceDirectives(
File "scripts/generate-resource-descriptions.py", line 193, in writeResourceDirectives
self.out.write(self.getConvertedResourceDirectives(daemon, resourcename))
File "scripts/generate-resource-descriptions.py", line 289, in getConvertedResourceDirectives
"description": self.getDescription(data),
File "scripts/generate-resource-descriptions.py", line 264, in getDescription
raise RuntimeError(f"Description is not plain text: '{description}'")
RuntimeError: Description is not plain text: 'List of valid TLSv1.2 and lower Ciphers; see :command:`openssl ciphers`'
Configuration error:
There is a programmable error in your configuration file:
Traceback (most recent call last):
File "/usr/local/lib/python3.8/site-packages/sphinx/config.py", line 350, in eval_config_file
exec(code, namespace)
File "/bareos/git/b-at-bareos/docs/manuals/source/conf.py", line 417, in <module>
subprocess.check_call(
File "/usr/lib64/python3.8/subprocess.py", line 364, in check_call
raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['scripts/generate-resource-descriptions.py', '--sphinx', 'source/include/autogenerated/bareos-dir-config-schema.json']' returned non-zero exit status 1.
Member
Author
|
I did the description changes in a minimal way, by rewriting the description in the C code ( |
Member
Author
|
@bruno-at-bareos When you finished your review, I'd like to squash some of the commits together. |
bruno-at-bareos
approved these changes
Apr 9, 2024
2f3792e to
3353a23
Compare
6 tasks
Explain that description strings in ResourceItem structures are plain text only.
Also clarifiy the description and fix the resource type to STRING. Co-authored-by: Bruno Friedmann @bareos <89836284+bruno-at-bareos@users.noreply.github.com>
82f6c2c to
f3e6b11
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Thank you for contributing to the Bareos Project!
Document and make sure, that ResourceItem descriptions are plain text.
Please check
If you have any questions or problems, please give a comment in the PR.
Helpful documentation and best practices
Checklist for the reviewer of the PR (will be processed by the Bareos team)
Make sure you check/merge the PR using
devtools/pr-toolto have some simple automated checks run and a proper changelog record added.General
Source code quality