From c20868cc84b63441ced72a166c913c64b3742dc8 Mon Sep 17 00:00:00 2001 From: Stephanie Labasan Brink Date: Wed, 8 Nov 2023 11:15:00 -0800 Subject: [PATCH] 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 | 4 +- docs/PerfFlowAspectDevel.rst | 77 ++++++++++++++++++++++++++++++++---- docs/conf.py | 6 ++- docs/developer.rst | 73 ---------------------------------- docs/requirements.txt | 2 + 5 files changed, 78 insertions(+), 84 deletions(-) delete mode 100644 docs/developer.rst create mode 100644 docs/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml index fd263ed7..deeb34a5 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/docs/PerfFlowAspectDevel.rst b/docs/PerfFlowAspectDevel.rst index d95e9616..b621bf74 100644 --- a/docs/PerfFlowAspectDevel.rst +++ b/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 +`_, and a production +container with PerfFlowAspect you can use for application development outside of +that. This is done via the `.devcontainer +`_ +directory. You can follow the `DevContainers 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. diff --git a/docs/conf.py b/docs/conf.py index 39b90d43..1e9580e6 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/developer.rst b/docs/developer.rst deleted file mode 100644 index fc024afc..00000000 --- a/docs/developer.rst +++ /dev/null @@ -1,73 +0,0 @@ -############################ - PerfFlowAspect Development -############################ - -This is a short developer guide for using the included development environment. -We provide both a base container for `VSCode -`_, and a production -container with PerfFlowAspect you can use for application development outside of -that. This is done via the `.devcontainer -`_ 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. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..c625976a --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx==7.2.6 +sphinx-rtd-theme==1.3.0