Link from Docbook dev docs to Markdown files #20530
Open
Conversation
This file contains 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
There seems to be a hesitance of adding developer documentation. Hopefully this makes it clear that people can just add Markdown files. This should also ensure that people reading the website do not miss the docs only in the source. The intent of putting it in the subtitle, even when that is not semantically ideal, is to have this visible also on the table of contents page.
martinpitt
requested changes
Jun 24, 2024
| @@ -53,6 +53,7 @@ | |||
|
|
|||
| <part id="development"> | |||
| <title>Developer Guide</title> | |||
| <subtitle>See also the documentation in <ulink url="https://github.com/cockpit-project/cockpit/tree/main/doc">the .md files directly in the doc folder of the cockpit source</ulink> and <ulink url="https://github.com/cockpit-project/cockpit/blob/main/HACKING.md">the HACKING.md file in the source</ulink>. These are currently not rendered here, but only the content of the folder doc/guide in the source is rendered here. Help is welcome in converting this documentation from Docbook XML to Markdown and merging these.</subtitle> | |||
There was a problem hiding this comment.
Squeezing this into the subtitle is too much of an abuse:
How about moving that into a new sub-file and including it here like the others?
Also, HACKING.md doesn't really belong here. This developer guide is about the cockpit API, i.e. how to use it to create your own pages. HACKING.md is about developing on cockpit itself. I don't mind much mentioning it here somewhere, but this is too prominent and distracting.
tree/main/doc is more useful, in particular protocol.md, but also the other files.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
There seems to be a hesitance of adding developer documentation.
Hopefully this makes it clear that people can just add Markdown files.
This should also ensure that people reading the website do not miss the
docs only in the source.
The intent of putting it in the subtitle, even when that is not
semantically ideal, is to have this visible also on the table of
contents page.