search

sccn / labstreaminglayer

LabStreamingLayer super repository comprising submodules for LSL and associated apps.
Other
544 stars 161 forks source link

Docs: re-use getting started page as repository README #42

Closed tstenner closed 4 years ago

tstenner commented 4 years ago

Github can render a subset of RST, so we can re-use the getting started guide 1:1 as the main repository README (preview).

The only feature I'm missing is the cross-reference support, i.e. :doc:`doc_name` and :ref:`some_section`.

cboulay commented 4 years ago

Is there any way to render README.rst at https://labstreaminglayer.readthedocs.io/info/README.html ? i.e., can the docs access something in a parent directory? The goal is to avoid copy-pasting.

agricolab commented 4 years ago

https://stackoverflow.com/questions/10199233/can-sphinx-link-to-documents-that-are-not-located-in-directories-below-the-root

tstenner commented 4 years ago

Is there any way to render README.rst at https://labstreaminglayer.readthedocs.io/info/README.html ?

Yes and no. I originally tried symlinking one to the other, but then the Github preview would only show the path instead of the contents. We could link add a symlink to /README.rst in docs/info/, but there's a certain OS starting with W that still has flaky support for four decade old features.

tstenner commented 4 years ago

On the other hand, everyone working on the documentation so far and readthedocs use Unix, so I've updated the PR to replace the page in docs/info with the symlink.

cboulay commented 4 years ago

I think anyone reading the documentation offline or on GitHub would see ../../README.rst in docs/info/getting_started.rst and understand that they should be looking to the README for info on how to get started. As long as this renders correctly in RTD then I'm OK with it.