Normalize contribution docs with Briefcase
freakboy3742 opened this issue · comments
What is the problem or limitation you are having?
Toga has a contribution guide for docs and code; so does Briefcase. However, there are some elements of the Briefcase docs that would be useful to include in the Toga docs.
Describe the solution you'd like
Replicate the sections of the Briefcase contribution guides that aren't Briefcase-specific in the Toga docs. The one section I've noticed in particular is the discussion about running CI checks locally as part of the PR submission process; there may be others.
Describe alternatives you've considered
Consolidate these docs upstream (on the beeware.org website) so that the content isn't duplicated unnecessarily. However, developing a good narrative flow with an external site like that may be complex.
Additional context
Having a single source for the identical portions would save work in the future, and prevent them from inevitably drifting apart again.
Absolutely agreed - the issue I have is the end-user ergonomics of needing 2 documents - a "these are the general rules" document, and a "this is how this specific project works" document, and how to maintain a narrative flow that doesn't result in people getting lost or requiring duplication.
One idea that occurred to me - although I have no idea how it would be implemented - would be to use a common source document, and include chunks of that common source as required. That would have the benefit of keeping the Briefcase docs on the Briefcase page, but would ensure that multiple versions say aligned.
Thinking out loud....
What if we leverage git submodules?
In this way, a new repo would contain the common documentation and the project repos would add this new repo as a submodule; then the docs could be built using a single source of truth for common documentation.
For instance: https://github.com/davidfischer/sphinx-with-submodules
Put together a quick PoC.
In a copy of the Briefcase repo, I added a new repo as a submodule in the docs directory. Then, I reference the common-1.rst file from the Briefcase's index.rst.
project repo: https://github.com/rmartin16/briefcase-test
common doc repo: https://github.com/rmartin16/beeware-common-docs-test
This all works rather seamlessly, IMO. There will need to be a workflow to bump the submodule commit in the project repos when the common doc repo is updated, though.
[edit] I guess a major issue this is likely to create is unaware contributors trying to build docs without the submodule....since git apparently doesn't clone submodules by default. So, anyone trying to build docs will need to run git submodule update --init or have run git clone --recurse-submodules initially...
What if we leverage git submodules?
That's definitely one way to avoid reproducing content; I'm not sure how I feel about it, though. I've historically avoided submodules unless I absolutely have to use them - I've found them to be one of those features that superficially works, but ends up making your life a whole lot more complicated in the long run (especially for contributors that haven't got experience with submodules - which is most of them).
At the risk of re-inventing the wheel - I wonder if it might be more reliable to use the same general approach, but build the subrepo cloning part as a build pre-processing step using regular git cloning.
I've found them to be one of those features that superficially works, but ends up making your life a whole lot more complicated in the long run (especially for contributors that haven't got experience with submodules - which is most of them).
This is fair and definitely one of my concerns for a submodule.
At the risk of re-inventing the wheel - I wonder if it might be more reliable to use the same general approach, but build the subrepo cloning part as a build pre-processing step using regular git cloning.
hmm...this definitely ventures in to wheel reinvention territory.
While this approach avoids the submodule, it introduces ambiguities that the submodule makes explicit. Notably, the current version of the "common docs" incorporated in to any single project's published docs is implicit. Now, we can create workflows around ensuring any updates committed to the "common docs" are more or less immediately pushed to dependent repos....but that doesn't remove the inherent implicit nature of which version of the "common docs" is being used.
Alternatively, if we're willing to automate the management of pulling and building docs from a remote repo, then it seems much more trivial to simply have tox ensure the submodule is initialized and updated prior to building the docs....rather than trying to manually clone a repo and add it to the project's docs.
But, even then, the "common docs" commit used for the submodule in a project repo still needs to be maintained. So, either way, we need a process to ensure updates in the "common docs" are disseminated to relevant repos and their docs are republished.
Given the submodule is only necessary to build the docs...and the only real way to build the docs is to run tox, I think much of the concern of contributors getting caught up in having to understand submodules can be avoided. That said, I don't have strong feelings and don't have much experience managing a submodule over time.
At the risk of re-inventing the wheel - I wonder if it might be more reliable to use the same general approach, but build the subrepo cloning part as a build pre-processing step using regular git cloning.
hmm...this definitely ventures in to wheel reinvention territory.
While this approach avoids the submodule, it introduces ambiguities that the submodule makes explicit.
That would depend a bit on the implementation - we could make our implementation use specific git hash or similar. However, at the very least, a non-trivial re-implementation of a not-insignificant portion of git submodules would be required.
Given the submodule is only necessary to build the docs...and the only real way to build the docs is to run
tox, I think much of the concern of contributors getting caught up in having to understand submodules can be avoided.
That's a fair point. My experience is that the core git submodule implementation "works" - it's just near-impossible for a normal human to consistently drive correctly. These problems stem from the fact that submodules aren't deeply integrated into the "default" git workflow, so you end up with stale checkouts, or incompatible checkouts, or something else like that.
If we can make the existence of the submodules completely transparent to the end user - so running tox e docs/docs-lint/docs-live completely manages submodule cloning, updating, etc; and the existence of the submodule doesn't impact on any other development behavior (e.g., causing issues switching between branches), then this might be an approach worth pursuing.