Merge pull request #1 from kbonney/documentation

Software package initialization

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build the documentation with Sphinx
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Setup nox
+        uses: excitedleigh/[email protected]
+      - name: Build docs
+        run: nox -s docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'docs/_build/html'
+  deploy:
+    name: Deploy documentation to GitHub Pages
+    needs: build
+    # Sets permissions of the GITHUB_TOKEN to allow deployment
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Setup pages
+        uses: actions/configure-pages@v3
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
+

.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Upload to PyPi
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools wheel twine
+    - name: Build and publish
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+      run: |
+        python setup.py sdist bdist_wheel
+        twine upload dist/*

.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: run tests
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [windows-latest, macOS-13, ubuntu-latest]
+        python-version: ['3.8', '3.9', '3.10']
+      fail-fast: false
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install pynumad
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+    - name: Test with pytest
+      run: |
+        pip install --upgrade pytest coverage
+        coverage run --source=pynumad --omit="*/tests/*" -m pytest

.gitignore

@@ -0,0 +1,3 @@
+docs/_build/*
+docs/_static/*
+__pycache__

docs/Makefile

@@ -0,0 +1,16 @@
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = ReadtheDocsSphinxTheme
+SOURCEDIR     = .
+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/conf.py

@@ -0,0 +1,60 @@
+from opensg import __version__
+
+# -- Project information -----------------------------------------------------
+project = u'opensg'
+copyright = u'2023 National Technology & Engineering Solutions of Sandia, LLC (NTESS)'
+author = u'opensg Developers'
+
+version = __version__
+release = __version__
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    # 'sphinx.ext.viewcode', # commenting out for now b/c bad render width
+    'sphinx.ext.napoleon',
+    'sphinxcontrib.bibtex',
+]
+napoleon_use_rtype = False
+viewcode_import = True
+numpydoc_show_class_members = True
+numpydoc_show_inherited_class_members = False
+numpydoc_class_members_toctree = False
+autodoc_member_order = 'bysource'
+autoclass_content = 'both'
+bibtex_bibfiles = ['refs/publications.bib','refs/conclusion.bib']
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+language = "en"
+numfig = True
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '_user']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+
+html_theme = 'pydata_sphinx_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+html_style = 'css/my_style.css'
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'opensgdoc'

docs/index.rst

@@ -0,0 +1,69 @@
+.. _home:
+
+pyNuMAD
+========
+
+The structural design and optimization of wind turbine blades is a
+complex task. In many cases it is difficult to find the optimal design
+of a turbine blade by hand, or by trial and error, and the software
+tools used for such designs are most effective when integrated into
+automated optimization and analysis algorithms. A new version of the
+software tool `pyNuMAD (Python Numerical Manufacturing And Design) <https://github.com/sandialabs/pyNuMAD>`_ for the design
+and modeling of wind turbine blades is developed and described. 
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   user-guide/index
+   contributing
+   apidoc/pynumad
+   reference
+   release-notes
+   publications
+   license
+
+.. _intro-citation:
+
+Citing NuMAD
+===============
+
+To cite pyNuMAD, please utilize the reference below.
+
+[1] Camarena, E., Anderson, E., Bonney, K. L., Clarke, R. J., & Paquette, J. (2023). pyNuMAD 1.0.0. Zenodo. https://doi.org/10.5281/zenodo.10023189
+
+
+
+.. _developers:
+
+pyNuMAD Developers
+=====================
+
+pyNuMAD has been developed by `Sandia National Laboratories 
+(Sandia) <https://energy.sandia.gov/programs/renewable-energy/wind-power/>`_, 
+funded by the U.S. Department of Energy’s Wind Energy Technologies Technologies Office. 
+
+
+Current members of the development team include:
+
+- Joshua Paquette (“Josh”) (Sandia - PI)
+- Evan Anderson (Sandia)
+- Ernesto Camarena (Sandia)
+- Kirk Bonney (Sandia)
+- Ryan James Clarke (Sandia)
+
+
+Funding
+=======
+
+Development and maintenance of the NuMAD code is funded by the U.S. Department of Energy’s Wind Energy Technologies Office.
+Sandia National Laboratories is a multi-mission laboratory managed and operated by National Technology and Engineering Solutions 
+of Sandia, LLC., a wholly owned subsidiary of Honeywell International, Inc., for the U.S. Department of Energy’s 
+National Nuclear Security Administration under contract DE-NA0003525.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/user-guide/index.rst

@@ -0,0 +1,22 @@
+.. _user-guide:
+
+User’s Guide
+============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Get Started
+
+   overview
+   installation
+   getting-started
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Interface
+
+   blade_definition
+   meshing
+   beam_models
+   shell_models
+   solid_models

docs/user-guide/installation.rst

@@ -0,0 +1,47 @@
+.. _intallation:
+
+Installation 
+============
+
+Download pyNuMAD
+----------------
+
+The OpenSG source code is hosted on the `opensg GitHub repository <https://github.com/sandialabs/pyNuMAD>`_. 
+OpenSG users are recommended to clone the Github repository.
+Cloning the repository allows users to easily pull the latest updates to the pyNuMAD source code.
+These updates may improve the code's speed, accuracy and add additional functionality or advanced features.
+
+To download OpenSG using `git <https://git-scm.com/>`_, type the following in a git interface:: 
+
+    git clone https://github.com/sandialabs/pyNuMAD
+
+Installation
+------------
+
+To install OpenSG and create an environment where the code runs correctly, please execute the following steps:
+
+1. Download the OpenSG repository::
+
+    git clone https://github.com/sandialabs/pyNuMAD
+
+2. Create the conda environment named `opensg_env` using the `environment.yml` file::
+
+    conda env create -f environment.yml
+
+3. On some systems, there is a bug where `gmsh` must be installed through pip, rather than conda, to interface with `dolfinx` correctly.
+If this bug occurs for you please run the following commands::
+
+    conda remove gmsh
+    pip install gmsh
+
+4. Install the OpenSG package by running the following command in the root of the OpenSG repository::
+
+    pip install .
+
+Alternatively, to perform a development installation run::
+
+    pip install -e .
+
+
+.. Developers are recommended to install using the instructions on
+.. :ref:`contributing<contributing>` page.

environment.yml

@@ -0,0 +1,21 @@
+name: opensg_env
+channels:
+  - conda-forge
+dependencies:
+  - python=3.10
+  - numpy
+  - scipy
+  - mpi4py
+  - meshio
+  - petsc4py
+  - yaml
+  - contextlib2  # For compatibility
+  - pathlib
+  - typing-extensions
+  - fenics-dolfinx 
+  - fenics-basix 
+  - fenics-ufl
+  - mpich 
+  - pyvista
+  - pyyaml
+  # - gmsh # I have to install this through pip for it to work.