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

[MRG] Replace most RST with Markdown #973

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

asoplata
Copy link
Collaborator

This replaces the reStructuredText (RST) versions of the README and most of the hand-written RST content on the code website ( https://jonescompneurolab.github.io/hnn-core/stable/index.html ) with similar versions using MyST Markdown ( https://www.sphinx-doc.org/en/master/usage/markdown.html#markdown ). For the reasons why this is a good idea, see the point of discussion in #969. Note that the only truly new text I have added is a small part in contributing.md which explains our use of Sphinx/etc. Roles, including versions for both RST and MD: https://github.com/asoplata/hnn-core/blob/mardownify-code-website/doc/contributing.md#writing-the-documentation . I think this will make it easier for people to contribute to the documentation, particularly for new users who likely will never know RST.

@asoplata asoplata added docs Documentation and tutorials website labels Jan 22, 2025
@asoplata
Copy link
Collaborator Author

asoplata commented Jan 22, 2025

Please note that for the vast, vast majority of content (like, except for <30 lines), the HTML output of these Markdown-parsed files should be exactly the same as the current RST-parsed files. With the exception of about 30 lines of text-content (that is relevant to using MD vs RST), I have not made any changes to the existing text, but instead only converted it.

@asoplata
Copy link
Collaborator Author

asoplata commented Jan 23, 2025

The only real "actual content" changes are here https://github.com/jonescompneurolab/hnn-core/pull/973/files#diff-ed8d59a5653a55110f94eeaed1a1dd3323a630b040dab3afaf4d6ef91b1cca84R190-R227 . All other changes are negligible, such as replacing the full-link to github issues in https://github.com/jonescompneurolab/hnn-core/pull/973/files#diff-5bfc69eca3a4a9bd8b35373ce858c9572aed84a4e0d29cefa291c74d72d3a66dR87-R104 with usage of the local gh-substitution sphinx extension, or typo and code linkage fixes in whats_new.md.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation and tutorials website
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant