Something to consider is keeping the site and the code in the same repo, which is what Calcite does.
Calcite builds a site (hosted on Apache rather than RTD) based on a Git branch (called “site”) of our main repo. This allows us to update the site without making a release. But we sometimes want to hold back site updates until there is a release. For example, if a commit adds a Java interface we don’t want to add it to the generated javadoc until that interface appears in a release. But if we make someone a committer, we want that change to the site to appear immediately. To achieve this, we have a CI job that cherry-picks from the main branch to the site branch, and part of the release process is to overwrite the site branch with the main branch. This isn’t clearly better or worse than your proposed two-repo process. But one advantage is that you can have a single PR, and single commit, that updates the code and the associated documentation. Julian > On Apr 30, 2024, at 2:02 PM, Riley Kuttruff <[email protected]> wrote: > > Hi everyone, > > Our RTD pages [1][2] are currently built from the Nexus repo master branch. > Under our current branching strategy, this would require any updates, fixes, > improvements or additions to the RTD documentation be done through a full > release. Obviously, that is less than ideal. > > I would suggest that we move those files to a new repo (eg, apache/sdap-docs) > which would allow quicker and easier updates to the docs. > > What does the community think? > > I will add this is kind of an important issue at the moment because a) our > docs builds are failing and b) an issue with the quickstart guide has been > found and needs fixing. > > Thanks, > Riley > > [1] https://incubator-sdap-nexus.readthedocs.io/en/latest/ > [2] https://readthedocs.org/projects/incubator-sdap-nexus/
