Initial TabPy Documentation

[WillAyd]

Nothing too fancy here but given how critical documentation is to open source projects I wanted to make sure we got this set up. This is using the RTD theme and is literally just including the MD files currently housed in docs. It looks as follows:

Logical follow ups here would be to autogenerate API documentation, restructure / add content, automate building and host somewhere like readthedocs.

If you wanted to build yourself note that sphinx_rtd_theme and recommonmark are dependent packages (along of course with sphinx).

For reference I've also zipped up a built copy.

html.zip

[0golovatyi]

@WillAyd This is interesting. Need some time to look at the changes and discuss with the team. Thanks for doing this!

[0golovatyi]

@WillAyd I am not sure I understand how the generated HTMLs are supposed to be used:

• Do contributors have to run the script each time any documentation change is made?
• Do we need to upload a new version of the HTMLs with any update?
• Is it for being used locally after downloaded and unpacked from .zip?

[WillAyd]

I can't claim to know all of the details, but generally if you chose something like readthedocs it comes pre-configured with a builder and will host files for you:

https://docs.readthedocs.io/en/latest/builds.html

As far as contributions go, there is a makefile for Un*x-based users and a .bat file for Windows users which can automate building for you. It's not a requirement for dev workflow though - only something you'd do if you actually changed the docs and want to see the result of that locally

[WillAyd]

Some more readthedocs info:

https://docs.readthedocs.io/en/latest/connected-accounts.html#connecting-your-account

[WillAyd]

@0golovatyi not sure what your teams view on having non-Tableau employees as part of the org on GH but if that's a possibility I could definitely look into the backend configuration of this in more detail.

Otherwise if you roll on your own and get stuck let me know - I have a good local contact at readthedocs who may be able to help

[0golovatyi]

@WillAyd After playing with this for some time I reverted the change because of the following reasons:

• make.bat does nothing for me
• we now need 2 copies for the documentation starting point (README.md/rst for github and docs/index.rst for readthedocs)
• links to .md files on readthedocs point to files which don't exist and I don't know how to fix those
• I personally find it confusing when for documentation I need to switch to different site

[0golovatyi]

In general, I think my biggest concern is I don't see how having documentation outside of the repo helps and what it brings in addition to what we already have.

[WillAyd]

I can't personally speak to main.bat but (assuming you are on Windows) could alternately use makefile from a linux subsystem.

As far as to your concerns on external documentation, I'm not aware of any serious open source project that doesn't do this. README.md is typically a quick reference solely for GH and will usually link people to external documentation.

Benefits include but are not limited to:

• Easier navigation / search / indexing
• More powerful linkage / markup languages (MD is simple but not as powerful as rst)
• Automatically generated API documentation

[WillAyd]

Here's some specific examples of projects where the documentation is external:

Cpython https://github.com/python/cpython

Tensorflow: https://github.com/tensorflow/docs/

Flask: https://github.com/pallets/flask

Django: https://github.com/django/django

etc...

[WillAyd]

• links to .md files on readthedocs point to files which don't exist and I don't know how to fix those

last comment (sorry for spam) but not sure what issues you were having. I noted in #219 some potential problems with the way targets were built which maybe is it? Alternately did you install the dependencies mentioned above?

Certainly building locally is a good first step. What error were you actually getting with the .bat file?

[0golovatyi]

So when documentation is built it contains links to file which don't exist, e.g. https://tabpy.readthedocs.io/en/latest/server-rest.md.

Not sure what dependencies I need, make.bat doesn't show any errors or other messages for me at all.

I don't think TabPy will be big enough project anytime soon for us to have dedicated documentation on some other site. We actually want the opposite thing - for everything to be in one place for easy reach.

[WillAyd]

Is recommonmark getting installed as a dependency in whatever process you've set up? Tough to guess without seeing how that's set up.

Probably better to start local first though. When you say make.bat doesn't provide messages are you executing that from a command shell or just double clicking on it? If the latter that feedback probably gets lost.

[0golovatyi]

I run it from the same command line I use for git and running unit tests for TabPy

[WillAyd]

If that's git bash then you can use the Makefile, so simply run:

make html

Within the doc folder. If it's git cmd (not sure if that still exists) then maybe try make.bat html if you haven't already

[0golovatyi]

>make html
>

Nothing happens.

Also we don't see having separate sources for documentation outside of TabPy repo so even if there is version of it on readthedocs it will contain the same exact information as what we already have in the repo. In general I understand why there may be need for a repo with documentation for another big repo, but I don't think it's our case.

[WillAyd]

I gotcha. Not sure what's going on locally. Most shells should at least give you some kind of result back

I'd still also ask you to consider it. Sphinx is very common for projects of all sizes.

We won't ever be able to autogenerate documentation for GH