Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Improve/refine the documentation generation process #3134

Open
jessebraham opened this issue Feb 13, 2025 · 0 comments
Open

Improve/refine the documentation generation process #3134

jessebraham opened this issue Feb 13, 2025 · 0 comments
Assignees
Labels
automation Repository automation using cargo-xtask documentation Improvements or additions to documentation

Comments

@jessebraham
Copy link
Member

#3131 added (hopefully) the last major changes for this functionality, but there's still some room for improvement here. Mostly just opening this issue to help myself keep track of what's left to do, and if anything else comes up people can let me know here as well and I'll take care of it.

  • The landing page generation needs to be updated to be aware of what's deployed on the server; if we do a subsequent documentation run which does not include all packages (i.e. a patch release of some package) then it currently will not generate the correct landing page.
    • For the initial round of publishing this will be fine, as we will be documenting all packages.
    • Probably this will just be another root-level manifest or something, will have to think about how we want to do this.
  • The documentation generation process is probably not as intuitive as it could be, and there are some caveats, so it would be nice to make this a bit nicer to use locally (i.e. not as part of a workflow).
    • Currently build-documentation-index requires build-documentation to have been run prior; this makes sense technically, but may trip some people up.
    • The JS fetching the manifest file will not work without a development server running locally. This can be accomplished easily via e.g. python -m http.server, but maybe we can make this a bit easier still.
    • Documenting the process would probably not be a bad idea either. This can just be added to xtask/README.md or somthing.
  • I still need to update the documentation.yml workflow. There are some limitations with GHA I'm trying to work around, hopefully will come up with something for this sooner than later.

I will add any additional points to the above list if I think of any, but for now I think this is mostly complete.

@jessebraham jessebraham added automation Repository automation using cargo-xtask documentation Improvements or additions to documentation labels Feb 13, 2025
@jessebraham jessebraham self-assigned this Feb 13, 2025
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
automation Repository automation using cargo-xtask documentation Improvements or additions to documentation
Projects
Status: Todo
Development

No branches or pull requests

1 participant