Merge pull request #15 from chrislupp/feature/documentation

Feature/documentation

Author: chrislupp

README.md

@@ -1,6 +1,7 @@
 ![Philote](doc/graphics/philote-python.svg)
 
 [![Unit and Regression Tests](https://github.com/chrislupp/Philote-Python/actions/workflows/tests.yaml/badge.svg)](https://github.com/chrislupp/Philote-Python/actions/workflows/tests.yaml)
+[![Deploy Documentation](https://github.com/chrislupp/Philote-Python/actions/workflows/documentation.yaml/badge.svg)](https://github.com/chrislupp/Philote-Python/actions/workflows/documentation.yaml)
 # Philote-Python
 
 Python library for using and creating Philote analysis servers.
@@ -19,15 +20,15 @@ The installation process requires the following tools to be installed:
 - importlib.resources
 
 Additionally, the following dependencies are required by Philote MDO and will be
-installed automatically during the installation process (if not process):
+installed automatically during the installation process:
 
 - numpy
 - grpcio
 
 
 ## Installation
 
-The Philote MDO Python bindings require a two step installation process. First,
+The Philote MDO Python library requires a two step installation process. First,
 make sure that `grpcio-tools` and `protoletariat` are installed. If not, they
 can be installed using pip. Note, that the first step of the installation
 process will not complete without these tools. Unlike the other dependencies,
@@ -59,7 +60,7 @@ version of gRPC that you have installed) and make it discoverable on your PATH.
 
 This package is licensed under the Apache 2 license:
 
-   Copyright 2022-2023 Christopher A. Lupp
+   Copyright 2022-2024 Christopher A. Lupp
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

doc/_config.yml

@@ -4,7 +4,7 @@
 title: Philote-Python
 author: Christopher A. Lupp
 logo: graphics/philote-python.svg
-copyright: 2022-2023
+copyright: 2022-2024
 
 # Force re-execution of notebooks on each build.
 # See https://jupyterbook.org/content/execute.html
@@ -53,3 +53,7 @@ html:
 sphinx:
   extra_extensions:
   - 'sphinx.ext.autodoc'
+  - 'sphinx.ext.napoleon'
+  - 'sphinx.ext.viewcode'
+  config:
+      add_module_names: False

doc/_toc.yml

@@ -3,9 +3,27 @@
 
 format: jb-book
 root: intro
-chapters:
-- file: tutorials/quickstart
-- file: tutorials/explicit_disciplines
-- file: tutorials/openmdao
-- file: tutorials/csdl
+parts:
+- caption: Getting Started
+  chapters:
+    - file: installation
+    - file: tutorials/quickstart
+
+- caption: Tutorials
+  chapters:
+  - file: tutorials/explicit_disciplines
+  - file: tutorials/implicit_disciplines
+  - file: tutorials/units
+
+- caption: Working with OpenMDAO
+  chapters:
+  - file: tutorials/openmdao
+
+- caption: Working with CSDL
+  chapters:
+  - file: tutorials/csdl
+
+#- caption: API Reference
+#  chapters:
+#  - file: api/explicit
 

doc/api/explicit.md

@@ -0,0 +1,2 @@
+# Explicit Discipline
+

doc/graphics/philote-logo.svg

@@ -0,0 +1,42 @@
+# Installation
+
+Philote-Python is a pure Python library. However, the installation process requires a few extra steps,
+as the gRPC/protobuf definitions must first be compiled into 
+
+
+## Requirements
+
+The installation process requires the following tools to be installed:
+
+- grpcio-tools
+- protoletariat
+- importlib.resources
+
+Additionally, the following dependencies are required by Philote MDO and will be
+installed automatically during the installation process:
+
+- numpy
+- grpcio
+
+
+## Compiling Definitions and Installation
+
+The Philote MDO Python library requires a two step installation process. First,
+make sure that `grpcio-tools` and `protoletariat` are installed. If not, they
+can be installed using pip. Note, that the first step of the installation
+process will not complete without these tools. Unlike the other dependencies,
+pip will not automatically install them during the package build. The first step
+is to compile the protobuf/gRPC files into python files. This is done by running
+(from the repository directory):
+
+    python setup.py compile_proto
+
+Once this step completes successfully, the package can be installed using pip:
+
+    pip install .
+
+or
+
+    pip install -e .
+
+for a development install.

doc/graphics/philote-python.svg

@@ -1,11 +1,6 @@
 # Philote-Python
 
-This is a small sample book to give you a feel for how book content is
-structured.
-It shows off a few of the major file types, as well as some sample content.
-It does not go in-depth into any particular topic - check out [the Jupyter Book documentation](https://jupyterbook.org) for more information.
 
-Check out the content pages bundled with this sample book to see more.
 
 :::{tableofcontents}
 :::

doc/graphics/philote_logo.svg

@@ -1,2 +1,4 @@
 (tutorials:csdl)=
-# Calling Philote Disciplines from CSDL
+# Calling Philote Disciplines from CSDL
+
+This feature is a work in progress and not yet complete.