Closed LexiconCode closed 7 months ago
Documentation can be viewed on my local repository https://lexiconcode.github.io/natlink/#/
Hi LexiconCode, I merged this PR in, but:
Sorry, I got lost on this issue. For the natlink documentation, I have no objections against markdown / docsify, but:
-Is there a possibility to edit in .md format, and then rename to .rst format, as they seems for most parts compatible? That would ensure that we can keep readthedocs.io!!
Hi LexiconCode, I merged this PR in, but:
Sorry, I got lost on this issue. For the natlink documentation, I have no objections against markdown / docsify, but:
- I am not sure where the documentation ends on the internet. I think it should, if possible, remain natlink.readthedocs.io
- For other projects, an important drawback is, that the autodocumentation from docstrings is not available. This is not an issue for the (introducing) natlink documentation. But IMO it is too bad for documentation of python files.
-Is there a possibility to edit in .md format, and then rename to .rst format, as they seems for most parts compatible? That would ensure that we can keep readthedocs.io!!
To answer your question regarding where does the documentation live on the internet. The documentation is GitHub itself through GitHub Pages.
As for a way to keep it hosted on ReadTheDocs. This really isn't feasible as I noted the issues with how md are routinely not rendered correctly. There isn't a way to change the format by changing file extensions.
So the last barrier here is to figure out how to manage documentation with doc strings. I understand what you're looking for there. Basically we need to find a way to generate doc strings with markdown without extension formats. So some research is needed.
Thanks Aaron, I come to this conclusion:
Fine to publish you markdown natlink documentation on github pages. We should make a link from natlink.readthedocs.io to that entry point and remove the rest of that site.
And keep using .rst and readthedocs for existing sites, as the maintainer wants it.
My worry was most, how users can find and access the documentation...
Do we agree?
This migrates the documentation to docsify.
ToDo:
Please provide the following feedback
ReadTheDocs platform with Sphinx has first-class support but markdown is not well supported.
Due to the points above the migration to docsify. A few things to note for those that contribute to the docs
index.html
in docs contains everything to configure docsify features. Initially is bare-bones but has been flushed out._sidebar.md
can be modified to add to to/restructure table of contents in the sidebar.### Migrating from Natlink 2.7: <!-- {docsify-ignore} -->