Documentation migration to docsify

[LexiconCode]

This migrates the documentation to docsify.

ToDo:

• [x] Deploy via github lexiconcode.github.io/natlink/#
• [x] Hyperlink URL documentation to readme (after PR merge)
• [ ] Document known DNS 16 API breaking changes and as issues on the repo
• [ ] Final review for cleanup of the docs

Please provide the following feedback

• Is the documentation concise?
• Does the organization make sense?
• is there anything that needs to be updated
  • please submit commits to this pull requests directly.

ReadTheDocs platform with Sphinx has first-class support but markdown is not well supported.

• For some reason markdown is not properly parsed and therefore what's displayed in an editor isn't representative to what's hosted
• Second there are bugs related to nested indexes for site navigation.

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.
• Markdown headings size auto populate sub entries in the sidebar. This takes a bit of experimentation to get right but easy to use once you figured it out.
• Headings can be ignored by docsify ### Migrating from Natlink 2.7: <!-- {docsify-ignore} -->
• README.md must be capitalized for github pages to work correctly

[LexiconCode]

Documentation can be viewed on my local repository https://lexiconcode.github.io/natlink/#/

[quintijn]

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!!

[LexiconCode]

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.

[quintijn]

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?