update install/build guides

Author: claudioperez

source/about/features/dropped.rst

@@ -4,8 +4,9 @@ Dropped Capabilities
 * All commands related to reliability analysis are dropped. This however does not include the commands for sensitivity analysis.
   In particular, the following are *not* supported:
 
-  * randomeVariable
+  * randomVariable
+
+* There are no plans to include the recently added ``damping`` commands.
 
-* There are no plan to include the recently added ``damping`` commands.
 * The recently added ``mesh`` and ``line`` commands of OpenSeesPy are replaced in |xara| by ``Model.surface``. 
   Motivation: ``mesh`` is unpredictable, questionably defined, and needlessly cumbersome.

source/conf.py

@@ -222,6 +222,7 @@
         "article_header_start": ["toggle-primary-sidebar.html", "breadcrumbs"]
     })
 
+g = "https://gallery.stairlab.io"
 html_context = {
     "root_doc": root_doc,
     "description": description,
@@ -230,7 +231,16 @@
 #   "doc_path": "<path-from-root-to-your-docs>",
 
     # HOME
-    "examples": [],
+    "examples": [
+            {"title": "Basics",      "link": f"{g}/examples/plane-0002/",     "image": "../_static/images/gallery/Example6.png", "description": "Learn the basics of drawing models."},
+            {"title": "Frames",      "link": f"{g}/examples/portal-moments/",     "image": "../_static/images/gallery/moments.png", "description": "Render structural models with extruded sections."},
+#           {"title": "Sections",    "link": f"{g}/examples/framesections/",     "image": "../_static/images/gallery/Torsion.png", "description": "Detailed analysis of structural cross sections."},
+            {"title": "Detailing",   "link": f"{g}/examples/example7/",     "image": "../_static/images/gallery/ShellFrame.png", "description": "."},
+            {"title": "Finite Rotations",  "link": f"{g}/examples/framecircle/",  "image": "../_static/images/gallery/ShellCircle-576x324.webp", "description": "Render finite deformations in constrained members like Cosserat rods and shells."},
+            {"title": "Versatility",     "link": f"{g}/examples/cablestayed/",  "image": "../_static/images/gallery/CableStayed02-576x324.webp", "description": "Import models from commercial platforms like ABAQUS."},
+#           {"title": "Motions",     "link": f"{g}/examples/framehelix/",  "image": "../_static/images/gallery/sign-light-2800x2558.webp", "description": "Coming soon."},
+#           {"title": "Interoperability", "link": f"{g}/examples/cablestayed/",  "image": "../_static/images/gallery/CableStayed02-576x324.webp", "description": "Coming soon."},
+    ],
     "features": [
         {"title": "Fast", "body": "Core components have been refactored to leverage modern C++ features, which has furnished substantial performance improvements over the alternative serial OpenSees interpreters."},
         {"title": "Free", "body": "All source code contributed to xara is licensed under a <em>pure</em> BSD."},

source/user/guides/compile.rst

@@ -1,6 +1,20 @@
+.. _user-guides-compile:
+
 Compile
 =======
 
+.. note::
+   
+   The procedure outlined in this guide will create a temporary compile configuration,
+   and clean up all intermediate files upon completion. This is useful for installing *xara* intro
+   a Python environment or making changes to the Python source code.
+   
+   If you wish to set up a persistent development environment to write C++ code, 
+   please refer to :ref:`develop <user-guides-develop>`.
+
+
+
+
 To compile Xara from source, follow these steps:
 
 1. Download the source repository to your computer by running:

source/user/guides/develop.rst

@@ -1,10 +1,202 @@
+.. _user-guides-develop:
+
 Develop
 =======
 
-1. Set up a development environment by following the instructions in :ref:`compile <user/guides/compile>`.
-2. Install build dependencies by running:
+This guide walks through the steps required to set up a development environment for *xara*
+that can be used to develop code in C++.
+
+
+Initial Setup
+-------------
+
+The following steps only need to be performed once to set up the development environment.
+
+1. Download the source repository to your computer by running:
+
+   .. code-block:: shell
+
+      git clone https://github.com/peer-open-source/xara
+
+2. Install *run-time* dependencies. You can install these with ``pip`` by running:
 
    .. code-block:: bash
+
+      python -m pip install xara
+
+   These are the libraries that will be needed in order to use Xara once it is built. 
+
+3. Install *compile-time* dependencies. These dependencies are only
+   needed for the compiling process. This is best done in an Anaconda environment.
+   For alternative package management systems, see the **Advanced** section below.
+   To install the required packages in an Anaconda environment, run:
+
+   .. tabs::
+
+      .. tab:: MacOS / Linux
+
+        .. note::
+           
+           On MacOS, make sure to install the Xcode command line tools by running
+           ``xcode-select --install`` from your terminal.
+
+        .. code-block:: bash
+            
+           conda install -c conda-forge fortran-compiler cxx-compiler c-compiler openblas openmpi cmake ninja
+
+
+      .. tab:: Windows
+
+         .. note::
+            
+            On Windows, make sure to install Visual Studio with the *"Desktop development with C++"* workload.
+
+         .. code-block:: bash
+
+            conda install -c conda-forge cmake ninja ifx_win-64 mkl-devel conda-forge/label/mkl_rc::blas
+
+
+4. Create a *persistent* build tree for C/C++ development:
+
+   a. Run the CMake *configure* operation. This should be carried out by running:
+
+      .. code-block:: shell
+
+         python setup.py cmake
+
+      This effectively runs the standard CMake *configure* procedure
+      (i.e., ``mkdir build && cd build && cmake ..``) but adds flags to ensure
+      the proper libraries and compilers are found. The name of the resulting
+      build directory will depend on factors such as your operating system,
+      and the version of Python that is installed in the environment. An example
+      might be ``./build/temp.linux-x86_64-cpython-39_local/``, where ``.`` refers
+      to the directory that contains ``setup.py``.
+
+   b. Navigate into the build tree that was generated by the last step, and
+      build the ``OpenSeesRT`` target to create ``libOpenSeesRT.so``:
+
+      .. code-block:: shell
+
+         cmake --build . --target OpenSeesRT -j8
+
+   c. When ``libOpenSeesRT.so`` is built in a persistent tree, the ``xara``
+      package needs to be told where to find it. This is done by setting
+      an environment variable with the name ``OPENSEESRT_LIB`` to point to
+      the location of ``libOpenSeesRT.so`` in the build tree.
+      You may want to add a line like the following to your shell
+      startup script (e.g., ``.bashrc``):
+
+      .. code-block:: bash
+
+          conda env config vars set OPENSEESRT_LIB="/path/to/libOpenSeesRT.so" -n my_environment
+
+
+5. Check that everything was built properly:
+
+   .. code-block:: shell
+
+      python -m xara
+
+   This will start a *xara* interpreter which can be closed by running
+   the ``exit`` command.
+
+
+
+
+
+Debug Builds
+------------
+
+The build type can be configured through the file ``setup.py``.
+For example, to change from a ``Release`` to ``Debug`` build, look for the following lines
+in ``setup.py`` and make the appropriate change:
+
+.. code-block:: python
+
+   cmake_configure_options = [
+       "-G", "Unix Makefiles",
+       *EnvArgs,
+       "-DCMAKE_BUILD_TYPE=DEBUG",
+   #   "-DCMAKE_BUILD_TYPE=RELEASE",
+   ]
+
+After this change, rerun the CMake configure and build steps described in
+**Develop → Create a persistent build tree**.
+
+
+Advanced
+--------
+
+The primary system dependencies required for compiling are LAPACK/BLAS and Tcl.
+Packages providing these libraries are listed below for various package
+management ecosystems.
+
+.. important::
+
+   When building in an Anaconda environment, you should install **all** dependencies
+   with ``conda`` or ``mamba``, and preferably from the ``conda-forge`` channel.
+   See the **Anaconda** tab below for details.
+
+.. tabs::
+
+   .. tab:: Linux (APT)
 
-      python -m pip install amoeba-build
+      The *APT* package manager is used by Debian-based Linux distributions, including Ubuntu.
+
+      .. list-table::
+         :header-rows: 1
+         :widths: 30 70
+
+         * - Dependency
+           - Package
+         * - LAPACK
+           - ``liblapack-dev``
+         * - BLAS
+           - ``libblas-dev``
+         * - Tcl
+           - ``tcl-dev``
+
+   .. tab:: Linux (Pacman)
+
+      The Pacman package manager is used by Arch Linux and Manjaro.
+
+      .. list-table::
+         :header-rows: 1
+         :widths: 30 70
+
+         * - Dependency
+           - Package
+         * - LAPACK
+           - ``lapack``
+         * - BLAS
+           - ``blas``
+         * - Tcl
+           - ``tcl``
+
+   .. tab:: Yum (CentOS, Red Hat Linux)
+
+      .. list-table::
+         :header-rows: 1
+         :widths: 30 70
+
+         * - Dependency
+           - Package
+         * - LAPACK
+           - ``lapack-devel``
+         * - Tcl
+           - ``tcl-devel``
+
+
+.. tabs::
+
+    .. tab:: MacOS / Linux
+
+        .. code-block:: bash
+
+            export OPENSEESRT_LIB="/path/to/your/compiled/libOpenSeesRT.so"
+
+    .. tab:: Windows (Powershell)
+
+        .. code-block:: powershell
 
+            $env:OPENSEESRT_LIB="/path/to/your/compiled/libOpenSeesRT.so"