Sphinx Documentation and read-the-docs

[schaffung]

We should start exploring as to how to spin up a sphinx document for the code base and also as to how to host it in read-the-docs. ( or any other hosting site which is free and open source ).

[nik-redhat]

Why not host on GitHub itself?

[aujjwal-redhat]

You mean Github pages right?

[nik-redhat]

You mean Github pages right?

Yup

[aujjwal-redhat]

Yeah that can be an option as well. But Sphinx is more dynamic in nature as we can customize it more as per our needs. Moreover along with rinohtype we can create PDF as well.

[nik-redhat]

Yeah that can be an option as well. But Sphinx is more dynamic in nature as we can customize it more as per our needs. Moreover along with rinohtype we can create PDF as well.

With sphinx you will create the docs, but where will you host it?

[aujjwal-redhat]

With sphinx you will create the docs, but where will you host it?

On readthedocs, we can host it. The following page explains the same: https://coderefinery.github.io/documentation/05-rtd/#:~:text=Running%20your%20own%20sphinx%20server,host%20your%20own%20Sphinx%20server.

[aujjwal-redhat]

Ok I have hosted the doc temporarily on my fork. @srijan-sivakumar @nik-redhat
https://aujjwal-redhat.readthedocs.io/en/latest/
So, now we can host the same on the original repo once we are ready with some structured content for Redant.

[schaffung]

I see that the readme is accessible currently. Now, I have couple of questions,

1. How easy is it to update these docs or rather put differently, if some code level changes are made, are the HTML files updated automatically or should the user concern himself with that too ?
2. How bulky is it making this repo ? We need to keep things lean. If need be we better separate out the documentation out of this taking a page out of gluster project where we have a separate entity called glusterdocs.

[aujjwal-redhat]

1. To change the docs you need to change the index.rst file. Its like readme itself. Even if you want to have multiple pages then just change that .rst file and it will get updated automatically. For ex: if I want to add a version history page, I will just create one version.rst file in the docs/source and then link that to the index or from wherever I want that page to be linked. It will automatically create a link on HTML side and the page will be hosted as well.
2. It has the extra css and js files so probably it will add some weight to the repo.

[schaffung]

Then let's not overburden the repo. Let's aim for something lean because we don't want the person using it to feel mad over the size.

To say in a pythonic way, the repo is for an automated test framework, so let it do one thing and in an efficient manner.

Let's focus on markdowns for documenting design considerations in each directory level for now as we code, for the UI based documentation, I'd leave it to you @nik-redhat and @aujjwal-redhat to see what might be the best way.

[nik-redhat]

Yeah, we should keep documentation in markdown and be it in the simplest possible way.
Considering, it's the documentation of the test framework only we don't want a very site and I think we can use Mkdocs (the one used by glusterdocs) here, it's very simple and minimalistic. Easy to manage as well.

[schaffung]

Would be better tracked as a discussion.