Update outdated D-Bus API docs #2267
Draft
Conversation
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
Calling them would crash but we only want them seen and documented. Usage, within a ./testing_using_container.sh shell: ```sh AGAMA_MAINFRAME_COSPLAY=1 ./setup-services.sh (cd doc/dbus/bus; ./seed.sh) ```
These are the ones that do not change semantics: - *.bus.xml now comes out with interfaces sorted by name - zbus now adds comments for standard interfaces
…t.dtd I was trying to be pedantic and only filter out known xmlstarlet errors But if it errors out the check will fail anyway, so be --quiet. Only woud do it with newer libxml/libxslt, oh joy
added a `make clean` target refentry-agama.css is my stupid attempt to do minimal styling Makefile has a quirky syntax that is a barrier to maintenance; separate shell scripts are an easy target for shellcheck too.
by running seed.sh in a testing_using_container.sh container Really should do it more often (automatically) as it nicely detects these API changes (commits found manually by me) 69ef2a0 Manager.CollectLogs c1f640e LocaleMixin 1860819 Progress.Steps 6901956 Software1.ListRepositories c37c01a Software1.SetUserPatterns 75f70d8 Software1.ProbeFinished f29f4ab Issues.All f29f4ab Locale.ListTimezones
gdbus-codegen is picky about what it lets through. You have to check that what you write actually gets rendered in the resulting HTML BTW there are remnants documenting an abandoned Agama.Network design: TODO: remove it https://github.com/search?q=repo%3Aagama-project%2Fagama+%2Forg.*Agama.*Network%2F&type=code
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.
Problem
On https://agama-project.github.io/ we have a hidden(!) /agama section with generated API docs. I don't know about the web UI part but the D-Bus part at /agama/dbus is outdated.
This is because updating it is a manual process that is easy to forget and easy to get wrong.
Also: s390...
Solution
Testing
Testing this is done by rendering the docs over and over (by
make ...TODO) and looking at the generated HTML to see if the texts is there at all and looks half decent.Oh I did add a trivial style sheet because the default one is too ugly even for me.
There is
make checkrun by CI but it only triggers once you start updating the docs by runningseed.shmanually.Screenshots
Documentation
Yes, how to make this easy for you people?
Remember to look at it from the user's perspective. Yes you have made the compiler happy.
But will the humans even know about your contribution? Sometimes they cannot miss it,
other times they need advertisement and explanation.
Look for relevant sections and adjust:
git ls-files '*.md'