Fix #228 Improve GitHub and Doxygen Docs. #230
Merged
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
Rename test input files, update test scripts, and update `.gitattributes` to treat `.input` files as binary, not `.in` files. This prevents cmake input templates ending in `.in` from being treated like binary test data files. In particular `doc/Doxyfile.in`.
This makes the name more consistent with other cmake template files.
Set `HAVE_DOT = YES` and `DOT_IMAGE_FORMAT = svg`. FTR I compared and svg diagrams are smaller than png as you would expect.
Make the doc target run in CMAKE_CURRENT_SOURCE_DIR and change `Doxyfile.in` to generate output into `OUTPUT_DIRECTORY = @CMAKE_CURRENT_BINARY_DIR@`. This ensures consistent doc filenames and references when using different build directorys, without leaking the full path of where it was built. See
Newer doxygen versions on Debian testing were complaining about this missing argument docstring entry in librsync.h.
This mostly just reformats paragraphs but also uses markdown links for root
docs CONTRIBUTING.md, NEWS.md, and TODO.md instead of Doxygen `\ref` links.
The root docs don't have `{#anchor}` doxygen anchors which is a pre-requisite
for markdown links to work on the old ubuntu_latest version of Doxygen. Note
currently CONTRIBUTING.md does have an anchor, but I want to test that it
actually fails before removing it.
Currently this document is only referenced by a markdown link in README.md, and for the old ubuntu_latest Doxygen version markdown links don't work if the doc has an anchor.
This makes the anchor name more consistent with the filename. Also change the title to be more consistent with the other usage doc rdiff.md.
This makes the anchor more consistent with the other docs.
This makes the anchor name consistent with the filename.
This makes the filename consistent with the doxygen anchor name.
This makes the title more consistent in the context of the other docs, and avoids confusion around callbacks used for other current (or future) APIs.
This is more consistent with other document titles and makes neater `\ref` links.
It seems a4wide is not supported in newer doxygen versions on Debian and is giving a warning.
This also makes the doxygen `\ref` links a little nicer.
Move doxygen docs from `*.c` files to their corresponding `*.h` files if there is one. Remove any "private" or "internal" markers from docs. It's already clear the librsync.h is the only public interface, but the rest of the docs are useful for understanding the code so we still want to generate them.
Member
Author
|
I'm happy with this now, and am going to merge it now. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
This improves the documentation so that Doxygen generates more complete documentation with diagrams, and also renders better and is more navigable as markdown docs on GitHub. It includes;
*.into*.inputand fix.gitattributessoDoxyfile.inis not considered binary.config.h.cmaketoconfig.h.infor consistency.HAVE_DOT = YESandDOT_IMAGE_FORMAT = svg. Change toPAPER_TYPE = a4to remove obsolete 'a4wide' value. In github actioncheck.ymlinstall graphviz dependency.Doxyfile.into generate output into the binary dir for consistent docs using different build directories.\reflinks for root markdown docs so they are navigable on GitHub but still render in Doxygen. Note the ubuntu_latest version of doxygen cannot yet use markdown links reliably enough to use them everywhere.\reflinks.\file <foo>.hdocstrings to all header and state-engine source files to include them in the Doxygen docs.*.cfiles into their corresponding*.hfiles and tidy them a bit.\paramdocstrings to silence newer doxygen warnings.