Re-apply lost updates in dev guides (Point72#202)

* Re-apply updates to build csp from source Signed-off-by: Pavithra Eswaramoorthy <pavithraes@outlook.com> * Add note about DCO in the Contribute.md Signed-off-by: Pavithra Eswaramoorthy <pavithraes@outlook.com> * Add back install notes about perl-ipc & git * Add back Using System Dependencies section Signed-off-by: Pavithra Eswaramoorthy <pavithraes@outlook.com> --------- Signed-off-by: Pavithra Eswaramoorthy <pavithraes@outlook.com>
Carreau · May 13, 2024 · 5103026 · 5103026
1 parent ba90a02
commit 5103026
Show file tree

Hide file tree

Showing 2 changed files with 51 additions and 33 deletions.
diff --git a/docs/wiki/dev-guides/Build-CSP-from-Source.md b/docs/wiki/dev-guides/Build-CSP-from-Source.md
@@ -10,6 +10,7 @@ CSP is written in Python and C++ with Python and C++ build dependencies. While p
   - [Clone](#clone)
   - [Install build dependencies](#install-build-dependencies)
   - [Build](#build)
+  - [A note about dependencies](#a-note-about-dependencies)
 - [Building with a system package manager](#building-with-a-system-package-manager)
   - [Clone](#clone-1)
   - [Install build dependencies](#install-build-dependencies-1)
@@ -18,6 +19,7 @@ CSP is written in Python and C++ with Python and C++ build dependencies. While p
   - [Install Python dependencies](#install-python-dependencies)
   - [Build](#build-1)
   - [Building on `aarch64` Linux](#building-on-aarch64-linux)
+- [Using System Dependencies](#using-system-dependencies)
 - [Lint and Autoformat](#lint-and-autoformat)
 - [Testing](#testing)
 - [Troubleshooting](#troubleshooting)
@@ -49,29 +51,16 @@ CSP has a few system-level dependencies which you can install from your machine
 
 The easiest way to get started on a Linux machine is by installing the necessary dependencies in a self-contained conda environment.
 
-Tweak this script to create a conda environment, install the build dependencies, build, and install a development version of CSP into the environment.
+Tweak this script to create a conda environment, install the build dependencies, build, and install a development version of `csp` into the environment. Note that we use [micromamba](https://mamba.readthedocs.io/en/latest/index.html) in this example, but [Anaconda](https://www.anaconda.com/download), [Miniconda](https://docs.anaconda.com/free/miniconda/index.html), [Miniforge](https://github.com/conda-forge/miniforge), etc, should all work fine.
 
 ### Install conda
 
 ```bash
-mkdir ~/github
-cd ~/github
+# download and install micromamba for Linux/Mac
+"${SHELL}" <(curl -L micro.mamba.pm/install.sh)
 
-# this downloads a Linux x86_64 build, change your architecture to match your development machine
-# see https://conda-forge.org/miniforge/ for alternate download links
-
-wget https://github.com/conda-forge/miniforge/releases/download/23.3.1-1/Mambaforge-23.3.1-1-Linux-x86_64.sh
-chmod 755 Mambaforge-23.3.1-1-Linux-x86_64.sh
-./Mambaforge-23.3.1-1-Linux-x86_64.sh -b -f -u -p csp_venv
-
-. ~/github/csp_venv/etc/profile.d/conda.sh
-
-# optionally, run this if you want to set up conda in your .bashrc
-# conda init bash
-
-conda config --add channels conda-forge
-conda config --set channel_priority strict
-conda activate base
+# on windows powershell
+# Invoke-Expression ((Invoke-WebRequest -Uri https://micro.mamba.pm/install.ps1).Content)
 ```
 
 ### Clone
@@ -88,31 +77,31 @@ git submodule update --init --recursive
 # Note the operating system, change as needed
 # Linux and MacOS should use the unix dev environment spec
 micromamba create -n csp -f conda/dev-environment-unix.yml
+
+# uncomment below if the build fails because git isn't new enough
+#
+# micromamba install -y -n csp git
+
+# uncomment below if the build fails because perl-ipc-system is missing
+# (this happens on some RHEL7 systems)
+#
+# micromamba install -y -n csp perl-ipc-system-simple
+
 micromamba activate csp
 ```
 
 ### Build
 
 ```bash
-make build
-
-# on aarch64 linux, comment the above command and use this instead
-# VCPKG_FORCE_SYSTEM_BINARIES=1 make build
+make build-conda
 
-# finally install into the csp_venv conda environment
+# finally install into the csp conda environment
 make develop
 ```
 
-If you didn’t do `conda init bash` you’ll need to re-add conda to your shell environment and activate the `csp` environment to use it:
+### A note about dependencies
 
-```bash
-. ~/github/csp_venv/etc/profile.d/conda.sh
-conda activate csp
-
-# make sure everything works
-cd ~/github/csp
-make test
-```
+In Conda, we pull our dependencies from the Conda environment by setting the environment variable `CSP_USE_VCPKG=0`. This will force the build to not pull dependencies from vcpkg. This may or may not work in other environments or with packages provided by other package managers or built from source, but there is too much variability for us to support alternative patterns.
 
 ## Building with a system package manager
 
@@ -187,6 +176,8 @@ Build the python project in the usual manner:
 ```bash
 make build
 
+# on aarch64 linux, comment the above command and use this instead
+# VCPKG_FORCE_SYSTEM_BINARIES=1 make build
 # or
 # python setup.py build build_ext --inplace
 ```
@@ -199,6 +190,10 @@ On `aarch64` Linux the VCPKG_FORCE_SYSTEM_BINARIES environment variable must be
 VCPKG_FORCE_SYSTEM_BINARIES=1 make build
 ```
 
+## Using System Dependencies
+
+By default, we pull and build dependencies with [vcpkg](https://vcpkg.io/en/). We only support non-vendored dependencies via Conda (see [A note about dependencies](#A-note-about-dependencies) above).
+
 ## Lint and Autoformat
 
 CSP has listing and auto formatting.
@@ -231,7 +226,7 @@ make fix-cpp
 make lint-py
 # or
 # python -m isort --check csp/ setup.py
-# python -m ruff csp/ setup.py
+# python -m ruff check csp/ setup.py
 ```
 
 **Python Autoformatting**
@@ -243,6 +238,24 @@ make fix-py
 # python -m ruff format csp/ setup.py
 ```
 
+**Documentation Linting**
+
+```bash
+make lint-docs
+# or
+# python -m mdformat --check docs/wiki/ README.md examples/README.md
+# python -m codespell_lib docs/wiki/ README.md examples/README.md
+```
+
+**Documentation Autoformatting**
+
+```bash
+make fix-docs
+# or
+# python -m mdformat docs/wiki/ README.md examples/README.md
+# python -m codespell_lib --write docs/wiki/ README.md examples/README.md
+```
+
 ## Testing
 
 CSP has both Python and C++ tests. The bulk of the functionality is tested in Python, which can be run via `pytest`. First, install the Python development dependencies with

diff --git a/docs/wiki/dev-guides/Contribute.md b/docs/wiki/dev-guides/Contribute.md
@@ -1,5 +1,10 @@
 Contributions are welcome on this project. We distribute under the terms of the [Apache 2.0 license](https://github.com/Point72/csp/blob/main/LICENSE).
 
+> \[!NOTE\]
+> CSP requires [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions.
+> This is enforced by a [Probot GitHub App](https://probot.github.io/apps/dco/), which checks that commits are "signed".
+> Read [instructions to configure commit signing](Local-Development-Setup#configure-commit-signing).
+
 For **bug reports** or **small feature requests**, please open an issue on our [issues page](https://github.com/Point72/csp/issues).
 
 For **questions** or to discuss **larger changes or features**, please use our [discussions page](https://github.com/Point72/csp/discussions).