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 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/
