Fix docs html rendering (#126)

* fix docs html rendering

- add requirements.txt
- update conf.py

* add updated developer page to docs

* fix broken URL

.readthedocs.yml

@@ -23,4 +23,6 @@ sphinx:
 formats: all
 
 # Optionally set the version of Python and requirements required to build your docs
-
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/PerfFlowAspectDevel.rst

@@ -1,12 +1,73 @@
-..
-   # Copyright 2021 Lawrence Livermore National Security, LLC and other
-   # PerfFlowAspect Project Developers. See the top-level LICENSE file for
-   # details.
-   #
-   # SPDX-License-Identifier: LGPL-3.0
-
 ###################
  Developer's Guide
 ###################
 
-This page is currently under construction.
+This is a short developer guide for using the included development environment.
+We provide both a base container for `VSCode
+<https://code.visualstudio.com/docs/remote/containers>`_, and a production
+container with PerfFlowAspect you can use for application development outside of
+that. This is done via the `.devcontainer
+<https://code.visualstudio.com/docs/remote/containers#_create-a-devcontainerjson-file>`_
+directory. You can follow the `DevContainers tutorial
+<https://code.visualstudio.com/docs/remote/containers-tutorial>`_ where you'll
+basically need to:
+
+#. Install Docker, or compatible engine
+#. Install the Development Containers extension
+
+Then you can go to the command palette (View -> Command Palette) and select
+``Dev Containers: Open Workspace in Container.`` and select your cloned
+PerfFlowAspect repository root. This will build a development environment. You
+are free to change the base image and rebuild if you need to test on another
+operating system! When your container is built, when you open ``Terminal -> New
+Terminal`` you'll be in the container, which you can tell based on being the
+"vscode" user. You can then proceed to the sections below to build and test
+PerfFlowAspect.
+
+**Important** the development container assumes you are on a system with uid
+1000 and gid 1000. If this isn't the case, edit the ``.devcontainer/Dockerfile``
+to be your user and group id. This will ensure changes written inside the
+container are owned by your user. It's recommended that you commit on your
+system (not inside the container) because if you need to sign your commits, the
+container doesn't have access and won't be able to. If you find that you
+accidentally muck up permissions and need to fix, you can run this from your
+terminal outside of VSCode:
+
+.. code:: console
+
+   $ sudo chown -R $USER .git/
+   # and then commit
+
+***************************
+ Installing PerfFlowAspect
+***************************
+
+Once inside the development environment, you can compile PerfFlowAspect:
+
+.. code:: console
+
+   export PATH=/usr/local/cuda-12.1/bin/:$PATH
+   cd src/c
+   mkdir build
+   cd build
+   cmake -DCMAKE_CXX_COMPILER=clang++ -DLLVM_DIR=/usr/lib/llvm-10/cmake ..
+   make
+   sudo make install
+
+If you want to run tests, cd to where the tests are, and run a few!
+
+.. code:: console
+
+   cd src/c/build/test
+   ./t0001-cbinding-basic.t
+
+Note that if you don't have a GPU, these probably will error (I do not)! Here is
+how to run Python tests:
+
+.. code:: console
+
+   cd src/python/test
+   ./t0001-pybinding-basic.t
+
+You'll again have issues without an actual GPU. And that's it! Note that we will
+update this documentation as we create more examples.

docs/conf.py

@@ -25,7 +25,9 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = [
+    'sphinx_rtd_theme'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -91,7 +93,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx==7.2.6
+sphinx-rtd-theme==1.3.0