Closed keithing closed 6 years ago
FWIW, reStructuredText has the "include" directive. We could use the start-after
and end-before
options to mark part(s) of README.rst
(which is updated more often and is the single source of truth for all updates, e.g., the new notes about setting up an API key on Windows 10 from #252) and include them in index.rst
(which contains Sphinx docs-specific items like the toctree
that we probably don't want to include in README.rst
).
I really like the idea of combining them. I don't think that we can use the same page for both exactly as-is; the documentation index page has links on it that we want to keep, but which don't seem quite right for the GitHub readme. There could be a modified page which works for both. Jackson's suggestion could be a way to create a single source of truth for some of these important documentation items.
Per offline discussion with Keith, I'll take this issue on.
@stephen-hoover what do you think about replacing index.rst (which is the landing page on readthedocs) to the README? It looks like there is a lot of overlapping documentation and I've had users expression confusion to me about why certain docs appear in the readme vs readthedocs.