Merge pull request #4

developer_documentation

.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/source/conf.py
+  fail_on_warning: true

CMakeLists.txt

@@ -1,46 +1,25 @@
 cmake_minimum_required(VERSION 3.17)
 
-project(src/eesunhong LANGUAGES Fortran CXX)
-
-if("$ENV{SKIP_CMAKE_BUILD}" STREQUAL "1")
-    message(STATUS "Manual build set, skipping build.")
-    return()
-endif()
+project(eesunhong LANGUAGES Fortran CXX)
 
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
-set(BUILD_TESTING OFF)
-include(FetchContent)
-FetchContent_Declare(
-        fortran_stdlib
-        GIT_REPOSITORY https://github.com/fortran-lang/stdlib.git
-        GIT_TAG fb4ca801f0c8e0ed09f9d137c620676fa348ebdd  # v0.2.1
-)
-FetchContent_MakeAvailable(fortran_stdlib)
-set(BUILD_TESTING ON)
-
-FetchContent_Declare(
-        VBBinaryLensing
-        GIT_REPOSITORY https://github.com/golmschenk/VBBinaryLensing.git
-        GIT_TAG bd7b19ce606261cb1ae5eebd800baa441d7d9bd2  # Fork made to be used as eesunhong library.
-)
-FetchContent_MakeAvailable(VBBinaryLensing)
+include(cmake/skipBuildBranch.cmake)
+include(cmake/fetchStdlib.cmake)
+include(cmake/fetchVbbl.cmake)
 
 add_library(polyroots OBJECT third_party/polyroots-fortran/polyroots_cmplx_roots_gen.f90)
 add_library(roots OBJECT third_party/roots-fortran/root_module.F90)
+
 add_library(eesunhong_internal OBJECT src/eesunhong_recipes_replacements.f90 src/geo_par.f src/eesunhong_geo_par_c_wrapper.f90)
 target_link_libraries(eesunhong_internal PUBLIC fortran_stdlib)
 
-add_custom_target(dummy_to_force_build_order)
-add_dependencies(dummy_to_force_build_order eesunhong_internal)
-
 add_library(eesunhong_fortran_library SHARED $<TARGET_OBJECTS:eesunhong_internal> $<TARGET_OBJECTS:roots> $<TARGET_OBJECTS:VBBinaryLensing>)
 target_link_libraries(eesunhong_fortran_library PUBLIC fortran_stdlib)
 # Without this was defaulting to CXX which was resulting in warnings with compact unwinding.
 set_target_properties(eesunhong_fortran_library PROPERTIES LINKER_LANGUAGE Fortran)
 
 add_library(eesunhong_complete_static STATIC $<TARGET_OBJECTS:eesunhong_internal> $<TARGET_OBJECTS:polyroots> $<TARGET_OBJECTS:roots>)
-add_dependencies(eesunhong_complete_static dummy_to_force_build_order)
 target_link_libraries(eesunhong_complete_static PUBLIC fortran_stdlib)
 
 add_executable(eesunhong_main src/main.f third_party/minuit/minuit_94a_dblb.f src/fcnrvg4_Ctpar.f src/bilens.f src/critical.f
@@ -49,14 +28,4 @@ target_link_libraries(eesunhong_main PUBLIC eesunhong_complete_static VBBinaryLe
 # Without this was defaulting to CXX which was resulting in warnings with compact unwinding.
 set_target_properties(eesunhong_main PROPERTIES LINKER_LANGUAGE Fortran)
 
-if(SKBUILD)
-    set(library_directory "${SKBUILD_PLATLIB_DIR}")
-    set(binary_directory "${SKBUILD_PLATLIB_DIR}")
-else()  # Calling CMake directly instead of through scikit-build means this is a developer build.
-    set(library_directory ".")
-    set(binary_directory ".")
-    set(CMAKE_INSTALL_PREFIX .)
-endif()
-
-install(TARGETS eesunhong_fortran_library DESTINATION ${library_directory})
-install(TARGETS eesunhong_main DESTINATION ${binary_directory})
+include(cmake/install.cmake)

cmake/fetchStdlib.cmake

@@ -0,0 +1,9 @@
+set(BUILD_TESTING OFF)
+include(FetchContent)
+FetchContent_Declare(
+        fortran_stdlib
+        GIT_REPOSITORY https://github.com/fortran-lang/stdlib.git
+        GIT_TAG fb4ca801f0c8e0ed09f9d137c620676fa348ebdd  # v0.2.1
+)
+FetchContent_MakeAvailable(fortran_stdlib)
+set(BUILD_TESTING ON)

cmake/fetchVbbl.cmake

@@ -0,0 +1,6 @@
+FetchContent_Declare(
+        VBBinaryLensing
+        GIT_REPOSITORY https://github.com/golmschenk/VBBinaryLensing.git
+        GIT_TAG bd7b19ce606261cb1ae5eebd800baa441d7d9bd2  # Fork made to be used as eesunhong library.
+)
+FetchContent_MakeAvailable(VBBinaryLensing)

cmake/install.cmake

@@ -0,0 +1,11 @@
+if(SKBUILD)
+    set(library_directory "${SKBUILD_PLATLIB_DIR}")
+    set(binary_directory "${SKBUILD_PLATLIB_DIR}")
+else()  # Calling CMake directly instead of through scikit-build means this is a developer build.
+    set(library_directory ".")
+    set(binary_directory ".")
+    set(CMAKE_INSTALL_PREFIX .)
+endif()
+
+install(TARGETS eesunhong_fortran_library DESTINATION ${library_directory})
+install(TARGETS eesunhong_main DESTINATION ${binary_directory})

cmake/skipBuildBranch.cmake

@@ -0,0 +1,4 @@
+if("$ENV{SKIP_CMAKE_BUILD}" STREQUAL "1")
+    message(STATUS "Manual build set, skipping build.")
+    return()
+endif()

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,27 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'eesunhong'
+copyright = '2024, David Bennett, Greg Olmschenk'
+author = 'David Bennett, Greg Olmschenk'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']

docs/source/guides/guide_for_fortran_developers.rst

@@ -0,0 +1,68 @@
+Guide for Fortran developers
+============================
+
+Setting up the developer environment
+------------------------------------
+
+The only prerequisites before these steps are that you have git installed (which is included on many systems by default) and some version of Conda installed.
+
+#. Clone the repository and enter the cloned project directory.
+
+    .. code:: sh
+
+        git clone https://github.com/golmschenk/eesunhong
+        cd eesunhong
+
+#. Create a Conda virtual environment with the correct dependencies installed.
+
+    .. code:: sh
+
+        conda env create --file=environments.yml
+
+#. Activate the Conda environment.
+
+    .. code:: sh
+
+        conda activate eesunhong_env
+
+In the future, whenever working on developing ``eesunhong``, activate the existing environment with the above line. When you are done working, you can either deactivate the environment with ``conda deactivate`` or just close the terminal.
+
+Building
+--------
+
+``eesunhong`` uses CMake for building. CMake is similar to Make, but allows builds to be much more toolchain agnostic (compiler, operating system, etc) as well as providing many other useful features (such as automatically downloading dependencies). All commands expected from inside the project directory.
+
+To build, first configure the build with:
+
+    .. code:: sh
+
+        cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
+
+Then build with:
+
+    .. code:: sh
+
+        cmake --build build --config Debug
+
+Just the second build command is required for subsequent builds, and will only rebuild changed components.
+
+To clean the build, simply delete the build directory:
+
+    .. code:: sh
+
+        rm -rf build
+
+To build an optimized version, first clean the build, then run the configure and build commands again, but this time replacing ``Debug`` with ``Release``.
+
+To compile using ``ifort``, make sure ``ifort`` is available in the path, then run
+
+    .. code:: sh
+
+        export FC=ifort
+
+prior to the build commands.
+
+Adding source files
+-------------------
+
+The file specifying which source files to compile, ``CMakeLists.txt``, may look somewhat confusing to those unfamiliar to CMake, especially due to the complexity added by importing remote GitHub dependencies and building both a Python library and the main binary executable. For Fortran developers, the main piece you will likely need to change is to add additional source files to be compiled. In most cases, you should add your new source files to the statement starting with ``add_executable(eesunhong_main``. If the source files will include functions or routines that should be callable from Python, the should generally be included in the statement starting with ``add_library(eesunhong_internal``.

docs/source/index.rst

@@ -0,0 +1,45 @@
+.. eesunhong documentation master file, created by
+   sphinx-quickstart on Mon Jan  1 22:48:08 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to eesunhong's documentation!
+=====================================
+
+Installation
+------------
+
+To install ``eesunhong`` use
+
+.. code:: shell
+
+    pip install eesunhong
+
+Although not required, as is generally good practice for any development project, we highly recommend creating a separate virtual environment for each distinct project. For example, via Conda, creating a virtual environment for a project using ``eesunhong`` might look like
+
+.. code::
+
+    conda create -n eesunhong_env python=3.11
+
+Then before working, be sure to activate your environment with
+
+.. code:: shell
+
+    conda activate eesunhong_env
+
+Then install ``eesunhong`` within this environment.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   guides/guide_for_fortran_developers
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

environment.yml

@@ -3,3 +3,9 @@ channels:
   - conda-forge
 dependencies:
   - python=3.11
+  - gfortran>=13
+  - cxx-compiler>=1.7
+  - pip:
+      - cmake>=2.28
+      - ninja>=1.11
+      - fypp>=3.2