Skip to content
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

Linking installation and structure of README.md with installation.rst and structure.rst #56

Closed
MaGering opened this issue Mar 6, 2023 · 5 comments
Labels
documentation 📝 Improvements or additions to documentation

Comments

@MaGering
Copy link
Collaborator

MaGering commented Mar 6, 2023

With the pages on installation and structure we have redundant information in the README.md and the docs. This should be streamlined by keeping only one place and including this into both. But we can tackle this later on.

Originally posted by @nesnoj in #7 (review)

@MaGering
Copy link
Collaborator Author

MaGering commented Mar 6, 2023

I wanted to solve this by importing the respective section from README.md in the rst-file like this, for installation:

.. include:: ../../README.md
   :literal:
   :start-after: Installation
   :end-before: Further reading on structure, pipeline and conventions

However the options start-after and end-before are not implemented yet in m2r2 (see CrossNox/m2r2#31)

@MaGering
Copy link
Collaborator Author

MaGering commented Mar 6, 2023

A much more troublesome workaround would be via the options start-line and end-line:

.. mdinclude:: ../../README.md
   :start-line: 12
   :end-line: 47

But here you have to specify the line numbers, which can change as soon as the README.md is changed. Therefore this option is maintenance-intensive or is very error-prone if it is forgotten.

@MaGering MaGering added the documentation 📝 Improvements or additions to documentation label Mar 6, 2023
@MaGering MaGering self-assigned this Mar 6, 2023
@nesnoj
Copy link
Member

nesnoj commented Mar 15, 2023

Rediscuss as soon as we have decided for or against mkdocs

@nesnoj
Copy link
Member

nesnoj commented May 11, 2023

Waits for #88

@nesnoj
Copy link
Member

nesnoj commented Jun 12, 2023

Outdated as mkdocs were implemented in #88

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation 📝 Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants