Documentation - First Draft

[kmorhun]

This PR is a doozy~ It does the following:

1. Sets up sphinx documentation infrastructure
2. Integrates the existing BASICS.md and DATA_PREPARE.md readme's into the documentation
3. Rewires all hyperlinks to connect to other sphinx documentation pages, instead of other github pages
4. Re-organizes existing tutorial notebooks and wrote additional tutorial notebooks (for command line tile2net, python module tile2net, and using google colab for GPU access)
5. Adds an API reference, fixing existing docstrings and making it easy to recognize where the remaining missing docstrings are
6. Creates a comprehensive installation guide, including how to incorporate Colab or HPCs for GPU access
7. Sets up space for a "how to contribute" page and a changelog.

To run and test the sphinx documentation:

1. Ideally, you should be able to just run python -m pip install -e . to update the new packages in requirements-dev.txt
2. cd docs, and then run make html. This should generate a build folder in docs
3. To just serve the currently built html pages, first cd docs/build/html, and run python -m http.server
4. To auto re-build the site whenever there is a change in the source code, run sphinx-autobuild docs/source docs/build/html instead and access your local host to see the site.

If at some point during the process, you get errors about myst-parser not existing or sphinx-autobuild not being a command, you may need to manually pip install sphinx myst-parser sphinx-rtd-theme nbsphinx pandoc sphinx-autobuild sphinx-copybutton

Known places with potential for change:

1. Successfully adding images to the gallery in the examples tab
2. Changing the theme away from the read-the-docs theme
3. the quick_start_module.ipynb file should be run on another device that has a GPU, uncommenting the inference section, and saving the output to the file, so the documentation can properly display it.

Next steps:

1. Get the documentation in a state we are willing to publish
2. Host it on ReadTheDocs!

(Edit: added the make html step to testing instructions) (Edit: http.server not http:server and added sphinx-copybutton, dhodcz2)

[dhodcz2]

Thank you!

To run and test the sphinx documentation:

1. Ideally, you should be able to just run python -m pip install -e . to update the new packages in requirements-dev.txt
2. To just serve the currently built html pages, first cd docs/build/html, and run python -m http:server
3. To auto re-build the site whenever there is a change in the source code, run sphinx-autobuild docs/source docs/build/html instead and access your local host to see the site.

I am unable to locate docs/build/html after pip install. Here's /docs: make.bat Makefile source I would think that /build should be generated by sphinx, however I cannot find it. Is there an issue with the sphinx configuration or am I misinterpreting instructions? What am I missing?

[kmorhun]

You're right! I missed a part in the instructions: If you cd docs and then run make html, that should generate the build folder from which you can access the html files. I believe sphinx automatically untracks the build folder because it always gets modified every time you change the source code. It would not be difficult to start tracking the build folder if we would like to.

[kmorhun]

I assume you mean just the gallery images fail to load - all the other images should work, right?

[dhodcz2]

Running Sphinx v7.1.2
WARNING: html_static_path entry '_static' does not exist
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 12 source files that are out of date
updating environment: [new config] 12 added, 0 changed, 0 removed

(The black background and yellow text is my configuration)