This Site ========= This website is currently (20190922) constructed as follows: * Content written in ReST. * Generated by sphinx * Themed by sphinx-material_ * Served by flask * Bundled in a docker image * Brought to you by Google Cloud Run The following describes the various compenents required to "operate" the site. Hopefully this site is self-documenting enough. Good luck, future me. The Root Makefile ----------------- .. tip:: **tl;dr:** If it's been a while just take a look at the root ``Makefile`` before doing anything. The Makefile found under the project root is intended to simply your life. (As any Makefile should.) Currently (20190922) the constituent targets are: :all: Default target. Simply requires the ``pages`` target. I.e this just build the docs - that is, the content - and moves that generated content into the appropriate location of the application's static files. :docs: Use sphinx to build the site ``html`` files from the source ``rst`` files. .. note:: This target won't update the content served by the site, this will update/generate the html content in ``docs/build/html``. To generate new content and update what get's served (say, to see changes in when using the flask dev server), see the ``pages`` target. :pages: Sync ``andrewrosss_dev/static/pages/`` with the content in ``docs/build/html`` *after* generating new docs via the ``docs`` target. :dev-server: Start serving the Flask application using ``gunicorn``. Uses a single worker and 2 threads. :dist: Create a new distribution of the website source. Specifically, this just runs:: python setup.py sdist bdist_wheel :upload: Upload the distributions under ``dist/`` using ``twine``. Specifically, this runs:: python3 -m twine upload dist/* :version: Echo the current version string. :clean: Remove everything under ``andrewrosss_dev/static/pages/`` and ``docs/build/``. Updating Content ---------------- .. tip:: **tl;dr:** Add new ``.rst`` content in ``docs/source/``, run ``make pages`` from inside the root directory. So new content needs to be added. Great, how to proceed? The source ``.rst`` files that are expected by sphinx can be found in ``docs/source``. As such, adding content should be as easy as adding and new/editing an existing ``.rst`` file. (And presumably editing the global toc tree ...) Once you've added the new content, be it a plain ``.rst`` file, or a notebook, or whatever, the next step is to generate updated html. This *can* be done using the Makefile provided by sphinx, however the Flask application (which serves the pages) doesn't serve those pages directly. The files that Flask serves are the ones located in ``andrewrosss_dev/static/pages/``. So running something like ``make clean && make html`` from inside ``docs/`` won't break anything, you're just going to have to manually copy over the generated files into the ``andrewrosss_dev/static/pages/`` directory. Instead of doing what I just described, what you *should* do is, from the project root, run ``make pages`` (or ``make clean && make pages`` to rebuild from scratch.) The ``pages`` target in the root makefile first generates new html files using sphinx, and then rsync's ``docs/build/html/`` with ``andrewrosss_dev/static/pages/``, accomplishing what was described above in one command. So, **do this**. Theming ------- .. tip:: **tl;dr:** Look in ``docs/source/conf.py`` and consult `sphinx-material demo site`_. As of this writing this site is generate using the sphinx-material_ package. By far the best place to look for information how to modify the presentation of this site via this sphinx theme is to check out either the GH repo or the `sphinx-material demo site`_. That, said for theming options, you're probably going to want to edit `docs/source/conf.py` (as usual with sphinx). The Flask Application --------------------- .. tip:: **tl;dr:** Look in ``pages.py`` and ``andrewrosss_dev/``, and maybe re-read part 1 of `the Flask mega-tutorial`_ The flask application that is used to serve the static pages is *exceedingly* simple. Everything flask app-related that you'd likely need will be found in the ``pages.py`` module and the ``andrewrosss_dev/`` package. Moreover, for a "real" refresher as to what's going on, consult `the Flask mega-tutorial`_. The application structure (think file layout) follows almost exactly what is achieved by the end of part 1 of the mega-tutorial, the notable changes being:: microblog.py -> pages.py app/ -> andrewrosss_dev/ Otherwise, it's all the same. Note that there is a ``.flaskenv`` file that enables us to call:: flask run to start the flask dev server in debug mode, however there is also a make target :: make dev-server # from inside the root directory which starts up a small gunicorn server with the ``--reload`` switch on, this more closely resembles what's going on in the docker container. The Dockerfile -------------- Describe what's going on in the ``Dockerfile``. There's probably going to be something make-related here as well. Cloud Run --------- Describe what's required to host the site using Cloud Run. Maybe a bit of documentation on what it took so set it up? Cloudbuild ---------- Describe how cloud build is used to deploy new builds of the site. Note that it's possible that a lot of what might fit under `Cloud Run`_, above, might actually move to this section because it would be "automated away" by cloudbuild. .. _sphinx-material: https://github.com/bashtage/sphinx-material .. _sphinx-material demo site: https://bashtage.github.io/sphinx-material/ .. _the Flask mega-tutorial: https://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-i-hello-world