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.

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

Simplify workflow for updating documentation #14

Open
brookslogan opened this issue Nov 15, 2024 · 2 comments
Open

Simplify workflow for updating documentation #14

brookslogan opened this issue Nov 15, 2024 · 2 comments

Comments

@brookslogan
Copy link
Collaborator

brookslogan commented Nov 15, 2024

Migrating from memory of meeting.

Updating just documentation for data objects currently requires:

  • Updating docs in epidatasets.
  • Re-documenting downstream packages with latest epidatasets, as downstream packages inherit documentation.
  • Every developer pulling epidatasets to not reverse doc updates.
  • (Maybe some other things? Adjusting version bounds doesn't seem strictly necessary since it's just documentation, but might assist in forcing developers to stay in sync.)

Ideas for simplifying:

  • Replace downstream docs with just a single data re-exports topic with links to epidatasets documentation for each object. We get to keep the note about data(<obj name>) (and could add one about needing epidatasets attached for listing its data sets with just data()).
  • Remove downstream docs; just @export and that's it. ?/help should route to epidatasets documentation [since we Imports: it], assuming we have identical object naming. We lose the notes about not being able to use data(<obj name>), but that's an dated paradigm anyway, so hopefully not a huge loss.
  • Don't re-export at all downstream. This requires adding epidatasets:: and/or library(epidatasets) in various downstream examples and vignettes.
@brookslogan
Copy link
Collaborator Author

I'm trying out the only-@export approach in cmu-delphi/epiprocess#564 because CHECK was complaining about {epiprocess} in the copied documentation. (Trying to parse it as .Rmd stuff.)

@brookslogan
Copy link
Collaborator Author

It's a fight between roxygen2, CHECK, and pkgdown to get something that looks okay and passes all checks. I've ended up with

  • an internal re-export topic in epiprocess that I can't seem to get rid of the Format: section in (@format NULL doesn't appear to work)
  • direct links to epidatasets in the pkgdown reference

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant