Python -- Add a post sphinx deployment comment to the devlog (#238)

* add server in make
* Add to devlog
---------
Co-authored-by: Skenvy <>

python/Makefile

@@ -45,7 +45,7 @@ SPHINX_BUILD_SOURCE=sphinx-apidoc -Me -V $(PACKAGE_VERSION) -R $(PACKAGE_VERSION
 VERIFY_BUILT_MSG=echo "Exit if a change to the built Sphinx rst's is not committed"
 VERIFY_BUILT_ERR=git add docs && git diff --exit-code --cached --stat -- docs/
 TWINE=twine upload --config-file ./.pypirc --repository
-.PHONY: venv revenv clean clean_again pydoc_server verify_built_checkin docs test tox lint build upload_test upload
+.PHONY: venv revenv clean clean_again pydoc_server verify_built_checkin docs server test tox lint build upload_test upload
 SHELL:=/bin/bash
 
 # https://code.visualstudio.com/docs/python/environments
@@ -96,6 +96,11 @@ docs: clean
 	$(VE) $(SPHINX_BUILD_SOURCE)
 	$(VE) sphinx-build -a -b dirhtml -W --keep-going -n docs/source docs/build
 
+# http://localhost:8000/docs/build/
+# http://localhost:8000/docs/build/collatz/
+server:
+	python3 -m http.server 8000
+
 test:
 	$(VE) $(TEST)
 

python/devlog.md

@@ -73,6 +73,8 @@ Now we can look at why there are a bunch of errors, for what I thought was the m
 Now we can pick a [sphinx theme](https://www.writethedocs.org/guide/tools/sphinx-themes/). I like both the [Read the Docs Theme](https://github.com/readthedocs/sphinx_rtd_theme) and the [Guzzle Theme](https://github.com/guzzle/guzzle_sphinx_theme). "Read the docs" has the edge of ubiquity, and guzzle includes a warning it might not play nicely with "readthedocs" (I _imagine_ it's refering to deploying a build using guzzle on the read the docs hosting site). It appears that [sphinx-rtd-theme's requires](https://github.com/readthedocs/sphinx_rtd_theme/blob/master/setup.cfg) a `sphinx` version less than 7. The issue on [sphinx-rtd-theme to support sphinx version 7](https://github.com/readthedocs/sphinx_rtd_theme/issues/1463) has a comment that mentions another theme that wasn't listed on the sphinx themese site, [furo](https://github.com/pradyunsg/furo). It might not be "read the docs", but to the credit of the quote in its [Used By](https://github.com/pradyunsg/furo#used-by) section, if it's got traction on `pip`, it must be pretty solid. I guess we'll try `furo`! (Turns out there's more themes [here](https://sphinx-themes.org/#themes)).
 
 The initial appearance of the sphinx docs are pretty bare. If we look at [Furo's recommendations](https://pradyunsg.me/furo/recommendations/), one of them is [MyST](https://myst-parser.readthedocs.io/en/latest/intro.html), which is also recommended by [sphinx](https://www.sphinx-doc.org/en/master/usage/markdown.html). But in the process of trying to add anything else or edit it in anyway, sphinx is quickly becoming one of the more frustrating to work with auto-documentation tools out of this whole project. I don't want to have to learn a whole entire new file format, as debugging even simple issues that crop up requires an understanding of what's going on in the reStructuredText that the `*.rst` files are written in, and besides the effort of already having to locate some tool to extend sphinx with that advertises itself as making it possible to include markdown files, it not only doesn't fully explain how to _actually use it_ but there aren't any easy or consistant answers to find on SO for "how do I get sphinx to _actually_ do **X**", which ends up meaning, for the simple task of rendering the markdown in the `<repo-root>/python/README.md`, I've gone through about 5 or 6 different posts with several answers each suggesting that they managed to get sphinx to finally behave how they expected it to with some magic solution, but _none_ of them have worked here. I've managed to get the raw text of the file to be included, which was itself already an hour of digging around online, and every time it runs the build, myst appears to pop in a little message that doesn't really give any information about why it isn't trying to render the page. So far most of the answers have revolved around using an rst file next to the index rst file to `.. include:: ../../README.md`. At this stage, if I wasn't committed to getting it done with sphinx to have a demonstrable experience of sphinx assisted masochism, and I was actually trying to create documentation with an "easy to use" tool, I'd abandon sphinx and go use a tool that was _actually_ easy to use. That's not to say sphinx can't be powerful, or that there aren't great sites that are apparently written in sphinx.. so why is the barrier to entry high enough that trying to include a markdown file is an Achillies heel, for someone who just wants to auto gen some docs? It appears that copying the entire file and having a duplicate of it exist in here lets it properly render it, but that's a shitty expectation, to have a duplicate? Why can it not see the relative path _outside_ of the source folder. Symlinking, `ln -s ../../README.md README.md`, appears to let it work the same way. I _finally_ found a way to make it work, and it took locating [this SO answer](https://stackoverflow.com/a/69134918/9960809), althought frustraingly, the answer was apparently [in some FAQ on MyST's site](https://myst-parser.readthedocs.io/en/latest/faq/index.html#include-markdown-files-into-an-rst-file) all along, tucked out of site. [This SO answer](https://stackoverflow.com/a/48931594/9960809) gets an honourable mention, but now that we have an answer that allows us to inject the whole contents, _parsed_ of course, into the index, and it's one that _can_ accept paths to files outside of the docs source folder, we can just point to the regular readme and not worry about going via the symlink.
+
+It also turns out that, after believing I had sphinx in a place where it was working and I wouldn't need to worry about it anymore, after merging and deploying the sphinx built docs to gh-pages, the site was mangled garbage. It turns out this is because the jekyll deplyoment gh-pages do ignores folders / files that start with underscores, and doesn't include them in the generated site. Sphinx's solution to this was apparently the add an extension that would yield a `.nojekyll` file. But that file is required to be at the root of the gh-pages deployment location, i.e. it must be in the folder from which the site _would_ have been generated. It does nothing if it's in a subdirectory, which is our pattern here. So, with a bunch of files that sphinx has put in subdirectories it decided needed to start with underscores, the only option to get around with was to set up gh-pages as a proper jekyll deployment and add _all the files in sphinx's deployment_ to the list of specific inclusions.
 ### Empty Orphan
 We're now ready to add once again create an empty orphan branch;
 1. `git checkout --orphan gh-pages-python`