[Discussion] Docs rewrite

[jorwoods]

Currently, documentation is maintained on a separate branch, gh-pages, and written in Markdown. With all of the type hints that have been incorporated over the last few releases, IDE/LSP's will have better information about what function signatures are available and being used. Python's default way of making documentation available to users is through docstrings.

What I propose is that instead of separately maintaining the documentation, especially the user facing TSC API documentation, separately, that it be maintained through docstrings in the .py files. Then the markdown that is currently being used is converted to reStructuredText. This would open up the ability to use sphinx and its autodoc extension to read those docstrings and produce the web navigable documentation. I believe the docs could still be published to gh-pages, so URLs would not have to change.

.rst is definitely not as simple of a format as .md, but the ability to fetch docstrings and function signatures I think offers a clear advantage over continuing with markdown.

[jacalata]

@dzucker-tab, thoughts?

Our tooling would be constrained by having to work with our internal doc writing setup, which I'm not perfectly familiar with.

[bcantoni]

In the past we've talked about this idea internally as well. One big benefit in my mind is we might have better traction keeping the docs up to date with each PR, whether it's automated docstrings or other doc content that can all come together in one PR.

[jacalata]

902 : Consider moving docs from gh-pages branch back to ./docs folder

[jorwoods]

I had missed the prior conversation about this. Concern over docs updates being tied to package updates is a pretty big one. I know that I have found myself missing adding changes to docs and then doing smaller PRs to fix it later. I guess the question is if having them available in docstrings and in code PRs means the docs revisions are likely to be less frequent?

[jacalata]

Docs updates would have to go to /main, but we don't need to bump the package every time we update main. We'd hope not to have a stream of doc updates, but if we need to make some it won't be a real problem. Dan says 👍 on the branch change and probably doc-strings.

[jorwoods]

Ok. I'll progressively submit PRs and some conversions to the docs. I think it will take quite a while before the gh-pages branch can be really replaced.