documentation
documentation copied to clipboard
Consider pulling in information from other repositories
Ideally, we want to avoid duplication between the OpenSAFELY documentation and individual repositories. This reduces extra work in maintaining the same content in multiple places. It would also means you don't have the potential for one source being outdated.
For instance, there currently is a copy-paste of part of the output-publisher README in this part of the docs (under "Click here to read in more detail about the osrelease
command.")
Thoughts from Tech Team meeting :thought_balloon:
- It is useful for the OpenSAFELY documentation to contain information about tools. This information is not otherwise easily accessible on firewalled servers. That information may be duplicated from elsewhere.
- It is good for developers writing information about their software to have that close to them for managing it. That is, keeping this documentation repository as the single source is additional work for developers to frequently switch to maintain.
If it is possible to configure mkdocs to pull information from these other sources, in the same way that cohort extractor docstrings are included, this might solve the problem. Maybe this all goes into the Reference section of the documentation?
Questions :question:
- Which repositories are of interest?
- What information specifically do we want to pull in? This might be some combination of READMEs and/or docstrings and/or something else.
- How can we configure mkdocs to do this?