Refactor Docstrings and Publish a Basic API Reference Site

.github/workflows/gh_pages.yml

@@ -0,0 +1,37 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  make-pages:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: 3.13
+
+    - name: Install dependencies
+      run: |
+        pip install --upgrade pip
+        pip install ".[docs]"
+
+    - name: Build the documentation
+      run: |
+        jupyter-book build docs
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v4
+      with:
+        path: "docs/_build/html"
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.gitignore

@@ -149,3 +149,7 @@ landbosse/tests/*.csv
 # repository directoy, ignore them.
 outputs/
 inputs/
+
+# Docs build
+_autosummary
+_build

CHANGELOG.md

@@ -1,81 +1,84 @@
 # LandBOSSE Changelog
 
-## 2.0.0 (August 1, 2019)
+## 2.6.2 (February 26, 2026)
 
-- Refactored into an object-oriented programming (OOP) architecture.
-- Enable parallel computation of separate projects.
-- Created an interface that takes inputs and outputs from and to `.xlsx` spreadsheets.
-- Enhancements to all modules in model.
-- Black box tests.
-- Dictionary based interface to integrate with other modeling codes.
++ Docstrings are reformatted to display nicely on a Jupyter Book documentation site.
++ Creates a docs site at <https://nlrwindsystems.github.io/LandBOSSE>
++ Removes the old documentation site and configuration for a more modern Jupyter Book
+  style site published to GitHub Pages for anyone to read.
++ Overhauls the README to bring it up to date with the current installation instructions.
 
-## 2.1.1 (October 9, 2019)
+## 2.6.1 (September 30, 2025)
 
-- In the `costs_by_module_type_operation` tab, standardize all costs to USD/kW per project, cost per project, cost per turbine.
-- Improve docstrings in source code.
-- Refactor more functionality into a new `CostModule` class.
-- Clean up logging to use simple `print()` statements which are safe to use in multi-process parallel logging operations.
++ Updates the PyPI listing
 
-## 2.1.2 (October 24, 2019)
+## 2.6.0 (February 12 2025)
 
-- Add separated "numeric value" and "non-numeric value" to columns on the details sheet.
-- Add support to test current model output against previously known good model output to guard against regressions when the model is changed.
-- Add support for command line options to control validation, input folder and output folder so that environment variables are not needed.
-- Added documentation about command line operation with flowcharts about how LandBOSSE processes data according to the command line.
++ Add basic API to integrate LandBOSSE into WAVES
++ Tidy up of code to remove warnings
++ Update to continuous integration script
 
-## 2.1.3 (October 29, 2019)
+## 2.2.7
 
-- Removed an empty and unimplemented function from `DefaultMasterInputDict.py`.
++ Changed construction duration functionality.
++ Weather window can now be extended to an arbitrarily long length by duplicating the underlying wind data.
++ All modules now report the actual construction time they require to perform the scope of work they model.
++ ManagementCost now keeps the management crew onsite for only the time necessary to complete all scope of work.
 
-## 2.1.4 (November 1, 2019)
+## 2.2.6
 
-- Enhanced `.xlsx` input performance for faster execution time.
++ Fix setup.py to automatically find the `landbosse` package.
 
-## 2.1.5 (November 8, 2019)
+## 2.2.5
 
-- Added outputs for erection crew cost, wind multiplier and mobilization of each process of the erection to the details output sheet.
++ Fixed a solver problem that would hang during foundation calculations. This was a bug encountered in the upgrade to SymPy 1.5.1
++ Added post processing scripts to load data into PostgreSQL
 
-## 2.2.0 (November 24, 2019)
+## 2.2.2 (December 13, 2019)
 
-- Support for parametric variable grid search added.
++ Added support for crane breakdowns
++ Fixed a roads issue.
 
 ## 2.2.1 (December 12, 2019)
 
 + Support for discrete value lists for parameteric variables added.
-
 + Support for labor rate multipliers added.
 
-## 2.2.2 (December 13, 2019)
-
-+ Added support for crane breakdowns
-
-+ Fixed a roads issue.
-
-## 2.2.5
-
-+ Fixed a solver problem that would hang during foundation calculations. This was a bug encountered in the upgrade to SymPy 1.5.1
+## 2.2.0 (November 24, 2019)
 
-+ Added post processing scripts to load data into PostgreSQL
++ Support for parametric variable grid search added.
 
-## 2.2.6
+## 2.1.5 (November 8, 2019)
 
-+ Fix setup.py to automatically find the `landbosse` package.
++ Added outputs for erection crew cost, wind multiplier and mobilization of each process of the erection to the details output sheet.
 
-## 2.2.7
+## 2.1.4 (November 1, 2019)
 
-+ Changed construction duration functionality.
++ Enhanced `.xlsx` input performance for faster execution time.
 
-+ Weather window can now be extended to an arbitrarily long length by duplicating the underlying wind data.
+## 2.1.3 (October 29, 2019)
 
-+ All modules now report the actual construction time they require to perform the scope of work they model.
++ Removed an empty and unimplemented function from `DefaultMasterInputDict.py`.
 
-+ ManagementCost now keeps the management crew onsite for only the time necessary to complete all scope of work.
+## 2.1.2 (October 24, 2019)
 
++ Add separated "numeric value" and "non-numeric value" to columns on the details sheet.
++ Add support to test current model output against previously known good model output to guard against regressions when the model is changed.
++ Add support for command line options to control validation, input folder and output folder so that environment variables are not needed.
++ Added documentation about command line operation with flowcharts about how LandBOSSE processes data according to the command line.
 
-## 2.6.0 (February 12 2025)
+## 2.1.1 (October 9, 2019)
 
-+ Add basic API to integrate LandBOSSE into WAVES
++ In the `costs_by_module_type_operation` tab, standardize all costs to USD/kW per project, cost per project, cost per turbine.
++ Improve docstrings in source code.
++ Refactor more functionality into a new `CostModule` class.
++ Clean up logging to use simple `print()` statements which are safe to use in multi-process parallel logging operations.
 
-+ Tidy up of code to remove warnings
+## 2.0.0 (August 1, 2019)
 
-+ Update to continuous integration script
++ Refactored into an object-oriented programming (OOP) architecture.
++ Enable parallel computation of separate projects.
++ Created an interface that takes inputs and outputs from and to `.xlsx` spreadsheets.
++ Enhancements to all modules in model.
++ Black box tests.
++ Dictionary based interface to integrate with other modeling codes.

README.md

@@ -1,5 +1,10 @@
 # LandBOSSE
 
+[![PyPI version](https://badge.fury.io/py/NREL-landbosse.svg)](https://badge.fury.io/py/NREL-landbosse)
+[![Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![image](https://img.shields.io/pypi/pyversions/NREL-landbosse.svg)](https://pypi.python.org/pypi/NREL-landbosse)
+[![Jupyter Book](https://jupyterbook.org/badge.svg)](https://nlrwindsystems.github.io/NREL-landbosse)
+
 ## Welcome to LandBOSSE!
 
 The Land-based Balance-of-System Systems Engineering (LandBOSSE) model is a systems engineering tool that estimates the balance-of-system (BOS) costs associated with installing utility scale wind plants (10, 1.5 MW turbines or larger). It can execute on macOS and Windows. At this time, for both platforms, it is a command line tool that needs to be accessed from the command line.
@@ -11,34 +16,82 @@ Eberle, Annika, Owen Roberts, Alicia Key, Parangat Bhaskar, and Katherine Dykes.
 National Renewable Energy Laboratory. NREL/TP-6A20-72201.
 https://www.nrel.gov/docs/fy19osti/72201.pdf.
 
+## Installation
+
+For any installation, users should use a virtual environment. We recommend Miniconda or Anaconda,
+but any supporting PyPI or source installations are possible. Here, we'll work with conda for
+compatibility with other NREL tools.
+
+In the below, you can replace the name "landbosse" with any name you choose, and the Python version
+can be any that you prefer as long as it's supported by LandBOSSE.
+
+```bash
+conda create -n landbosse python=3.13 -y
+```
+
+### PyPI
+
+```bash
+pip install NREL-landbosse
+```
+
+### Source
+
+1. Navigate to your preferred installation location
+2. Clone the repo (or fork and clone your fork, if preferred).
+
+    ```bash
+    git clone https://github.com/NLRWindSystems/LandBOSSE.git
+    ```
+
+3. Enter the directory and install the local version
+
+    ```bash
+    cd LandBOSSE
+    pip install .
+    ```
+
+    Optional: `pip install -e .` for editable installations if you plan to modify the code itself.
+
 ## User Guides
 
-First, read the technical report to understand the big picture of LandBOSSE. In the technical report, you will find process diagrams, equations and the modules that implement them. Then, come back to this documentation and read the user guide.
+### First time running teh model
+
+At its most basic, the following setup is required, though the provided input data in `project_inpute_template`
+can be used to test out the model and view results before diving into configuring custom scenarios.
 
-In brief, LandBOSSE takes `.xlsx` spreadsheets, reads input data from tabs on the spreadsheets, and writes the results to an output `.xlsx` file. There are three sections in the user guide to demonstrate how to perform these steps.
+1. Create an "input" and "output" folder for LandBOSSE to access. If you are using a source
+   installation, then ensure the folders are not located inside the local copy of the repository.
+2. Create a `project_list.xlsx` like `LandBOSSE/project_list.xlsx` and a subfolder called
+   `project_data` inside of `inputs`.
+3. Each project in `project_list.xlsx` should have a corresponding Excel file in `project_data`
+   similar to the examples in `LandBOSSE/project_input_template/project_data`.
 
-The user guide comes in three parts:
 
-1. Software installation,
+### Running the model 
 
-2. Input data configuration, and
+Once the initial steps (above) are followed, we can run the model:
 
-3. Output data analysis.
+1. Activate your virtual environment: `conda activate landbosse
+2. Navigate to the top-level `LandBOSSE` folder
+3. Run the model: `python main.py -i input-folder-path -o output-folder-path` (be sure to replace
+   "input-folder-path" and "output-folder-path" with your respective input and output folders).
 
-### Software Installation
+All together
 
 ```bash
-pip install NREL-landbosse
+conda activate landbosse
+cd /path/to/LandBOSSE
+python main.py -i /path/to/inputs -o /path/to/outputs
+conda deactivate
 ```
 
-There are two options depending on whether you are a developer or an end user and what operating system you are running.
-
-- **Windows end-user**: If you run the Microsoft Windows operating system and aren't setting up as a developer who is going to be modifying the core library, these instructions are for you. [Find out how to configure Windows for end users.](installation_instructions/windows_end_user.md)
+4. View your results in the output folder.
 
-- **macOS end user** and **macOS developer**: If you run the macOS operating system, either as an end-user or as a developer, these instructions are for you. Both developers and end-users will need most of the steps. [Find out how to configure macOS for end users and developers.](installation_instructions/macos_developer.md)
 
-### Operation after the installation
+### Integrating LandBOSSE into your code
 
-Review the installation instructions on how to activate a virtual environment, if you haven't already.
+While LandBOSSE was originally designed as a CLI tool powered by Excel workbooks, an API also exists
+to run the model within another application.
 
-Then, read the [Operation and Folder Structure](installation_instructions/operation_and_folder_structure.md) for details on running the command that executes LandBOSSE from the command line.
+Further documentation coming soon

docs/_config.yml

@@ -0,0 +1,86 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: LandBOSSE
+author: National Laboratory of the Rockies
+# logo: logo.png
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/NLRWindSystems/LandBOSSE
+  path_to_book: docs
+  branch: main
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+sphinx:
+  extra_extensions:
+  - "sphinx.ext.autodoc"
+  - "sphinx.ext.autosummary"
+  - "sphinx.ext.napoleon"
+
+  config:
+    html_theme: sphinx_book_theme
+    html_theme_options:
+      use_issues_button: true
+      use_repository_button: true
+      use_edit_page_button: true
+      show_toc_level: 2
+      repository_url: "https://github.com/NLRWindSystems/LandBOSSE"
+      repository_branch: main
+      # icon_links: [
+      #   {
+      #       name: GitHub,
+      #       url: "https://github.com/NREL/WAVES",
+      #       icon: fa-brands fa-github,
+      #   },
+      #   {
+      #       name: PyPI version,
+      #       url: "https://pypi.org/project/WAVES/",
+      #       icon: "https://img.shields.io/pypi/v/WAVES?link=https%3A%2F%2Fpypi.org%2Fproject%2FWAVES%2F",
+      #       type: url,
+      #   },
+      #   {
+      #       name: Binder,
+      #       url: "https://mybinder.org/v2/gh/NREL/WAVES/main?filepath=examples",
+      #       icon: "https://mybinder.org/badge_logo.svg",
+      #       type: url,
+      #   },
+      # ]
+    language: 'python'
+    autosummary_generate: true
+    autodoc_default_options:
+      members: true
+      member-order: bysource
+      undoc-members: true
+      private-members: true
+      # special-members: true
+      # inherited-members
+      # show-inheritance
+      # ignore-module-all
+      # imported-members: true
+      # exclude-members
+      # class-doc-from
+      # no-value
+    autodoc_typehints: description
+    napoleon_use_admonition_for_notes: true
+    napoleon_use_rtype: false
+    nb_merge_streams: true