civisanalytics / civis-python

Civis API Python Client
BSD 3-Clause "New" or "Revised" License
34 stars 26 forks source link

Coalesce README and index.rst #253

Closed keithing closed 6 years ago

keithing commented 6 years ago

@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.

jacksonllee commented 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).

stephen-hoover commented 6 years ago

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.

jacksonllee commented 6 years ago

Per offline discussion with Keith, I'll take this issue on.