Where to put inter-repo docs?

[aesharpe]

What happens when you want to create docs that reference multiple repos?

The main example is adding new data to PUDL. Adding new data entails creating scraper to the pudl-scrapers repo, creating an archive in the pudl-zenodo-archive repo, and then add to the ETL in the pudl repo. Should the instructions for each of these steps live separately in the docs/README for each repo, all together in one place (where?), or some hybrid of the two?

[zaneselvans]

I think the nitty-gritty docs should probably live in the repo with the code that is being documented -- that makes it easier to ensure that the documentation is updated when a PR happens in that repo, and that the documentation and the code hopefully stays synchronized. But there's no reason not to link liberally between the documentation in different repos. We can use intersphinx to refer to modules / functions / classes / etc in other repositories, if we add them in the intersphinx section of docs/conf.py:

# In order to be able to link directly to documentation for other projects,
# we need to define these package to URL mappings:
intersphinx_mapping = {
    "arrow": ("https://arrow.apache.org/docs/", None),
    "dask": ("https://docs.dask.org/en/latest/", None),
    "geopandas": ("https://geopandas.org/en/stable/", None),
    "networkx": ("https://networkx.org/documentation/stable/", None),
    "numpy": ("https://numpy.org/doc/stable/", None),
    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
    "pytest": ("https://docs.pytest.org/en/latest/", None),
    "python": ("https://docs.python.org/3", None),
    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
    "setuptools": ("https://setuptools.pypa.io/en/latest/", None),
    "sklearn": ("https://scikit-learn.org/stable", None),
    "sqlalchemy": ("https://docs.sqlalchemy.org/en/latest/", None),
    "tox": ("https://tox.wiki/en/latest/", None),
}