Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 8, 2019

Conversation

tstenner
Copy link
Collaborator

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

@tstenner tstenner requested a review from cboulay November 27, 2019 09:00
@cboulay
Copy link
Collaborator

cboulay commented Dec 6, 2019

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
Copy link
Contributor

@tstenner
Copy link
Collaborator Author

tstenner commented Dec 6, 2019

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
Copy link
Collaborator Author

tstenner commented Dec 6, 2019

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
Copy link
Collaborator

cboulay commented Dec 8, 2019

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.

@cboulay cboulay merged commit fa48af0 into master Dec 8, 2019
@tstenner tstenner deleted the docs_readme branch December 9, 2019 08:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants