Skip to content

Commit d513ac3

Browse files
rafmudafrafmudaf
authored
Merge pull request NatLabRockies#9 from rafmudaf/main
Add architecture and build documentation
2 parents 1b9264b + f0982d3 commit d513ac3

1 file changed

Lines changed: 156 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 156 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,120 @@
11

2-
# WETOStack
2+
# WETO Stack
33

4-
This repository contains the source files for the documentation of the WETO Software Stack, which includes an entry guide for new users, multiple listings and categorization of the software models, software quality characterization, and notes from the developer and user engagement that created the WETOStack content. See [nrel.github.io/WETOStack/](https://nrel.github.io/WETOStack/) for more information.
4+
This repository contains the source files for the documentation of the WETO Software Stack,
5+
which includes an entry guide for new users,
6+
multiple listings and categorization of the software models,
7+
software quality characterization,
8+
and notes from the developer and user engagement that created the WETOStack content.
9+
See [nrel.github.io/WETOStack/](https://nrel.github.io/WETOStack/) for more information.
510

611
Copyright 2024 Alliance for Sustainable Energy, LLC.
712

8-
## Building the site
13+
## Repository Contents
14+
15+
This repository contains a variety of tools for analyzing the WETO Software Stack as well as
16+
reports from community engagement meetings and the source code for the documentation site.
17+
The repository is organized as follows:
18+
19+
- `.github/`: Configuration files for GitHub Actions jobs and GitHub Pages builds
20+
- `best_practices_report/`: LaTeX source files for the WETO Software Best Practices technical report
21+
- `docs/`: Source files for most of the content on the WETO Software Stack website
22+
- `entry_guide/`: Source files for the WETO Stack Entry Guide project
23+
- `software_attributes/`: Database files (YAMLs) and analysis scripts for portfolio analysis
24+
25+
## Dependencies
26+
27+
The Python-based analysis scripts and Jupyter Book project dependencies are listed in
28+
`requirements.txt`. These can be installed with `pip`:
29+
30+
```bash
31+
pip install -r requirements.txt`
32+
```
33+
34+
The entry guide project is built with Node Package Manager (`npm`), and the dependencies are
35+
listed in `entry_guide/package.json`. After installing `npm`, the dependencies are
36+
installed by running the install command within the entry guide directory:
37+
38+
```bash
39+
cd wetostack/entry_guide/
40+
npm install
41+
```
42+
43+
## Building the Website
44+
45+
The WETO Software Stack website consists of two distinct components:
46+
- Jupyter Book project that creates the primary structure and the majority of the content
47+
- WETO Stack Entry Guide implemented with VueJS
48+
49+
The Entry Guide should be built first, copied into the Jupyter Book project directory,
50+
and then the Jupyter Book project can be compiled. Refer to the
51+
[deploy_pages](https://github.com/NREL/WETOStack/blob/main/.github/workflows/deploy-pages.yaml)
52+
GitHub Actions workflow for more information.
53+
54+
**Note:** The Jupyter Book table of contents links to the Entry Guide via a web URL. When
55+
building the documentation locally, you should change the web URL for the Entry Guide in the
56+
table of contents to point to the Entry Guide `index.html` file locally.
57+
58+
### Building the Entry Guide VueJS Project
59+
60+
The Entry Guide uses [VueJS](https://vuejs.org), [VueFlow](https://vueflow.dev),
61+
[DagreJS](https://github.com/dagrejs/dagre), and a few other libraries in the TypeScript and
62+
Vue ecosystems.
63+
[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) is required to
64+
compile the Entry Guide project and install the dependencies.
65+
66+
The Entry Guide can be compiled as production quality or development quality.
67+
During active development, the development build is highly recommended as it provides a
68+
hot reload capability where changes made to the project contents are automatically recompiled
69+
and an open browser window will automatically render the changes.
70+
Modifications to the project configuration will not be automatically compiled.
71+
72+
To compile the Entry Guide in development mode, move into the `entry_guide/` directory
73+
and run the dev-build command:
74+
75+
```bash
76+
cd wetostack/entry_guide/
77+
npm run dev
78+
79+
# Terminal output:
80+
# VITE v6.2.2 ready in 200 ms
81+
#
82+
# ➜ Local: http://localhost:5173/
83+
# ➜ Network: use --host to expose
84+
# ➜ press h + enter to show help
85+
```
86+
This build process creates a local server accessible through the local URL shown
87+
(`localhost` + port).
88+
As changes are made to the source, the running build process automatically rebuilds.
89+
If there are errors in the code, the terminal window will show them.
90+
When they're fixed, the terminal will automatically rebuild and show the local URL again.
91+
92+
To do a production build, run the following command:
93+
94+
```bash
95+
npm run build
96+
97+
# Terminal output:
98+
# > entry_guide@0.0.0 build
99+
# > vue-tsc -b && vite build
100+
#
101+
# vite v6.2.2 building for production...
102+
# ✓ 120 modules transformed.
103+
# dist/index.html 0.48 kB │ gzip: 0.32 kB
104+
# dist/assets/index-C8-A469-.css 3.47 kB │ gzip: 1.19 kB
105+
# dist/assets/index-DjNIX96g.js 298.55 kB │ gzip: 99.24 kB
106+
# ✓ built in 616ms
107+
```
108+
The compiled files are put into the `entry_guide/dist/` directory. From there, the app can be
109+
opened into a browser by opening `entry_guide/dist/index.html`.
110+
111+
Finally, the Entry Guide is included in the WETO Software Stack website by copying the
112+
contents of the `dist` directory into `weto_stack/docs/_static/entry_guide`. Note that
113+
the Jupyter Book project table of contents must be modified to point to the local path
114+
to the Entry Guide's `index.html` file rather than the web URL that is set for the
115+
deployed project.
116+
117+
### Building the Jupyter Book Project
9118

10119
The site is built using [Jupyter Book](https://jupyterbook.org/intro.html).
11120
To build the site, run the following command:
@@ -33,15 +142,52 @@ You can look at your book by opening this file in a browser:
33142
_build/html/index.html
34143
Or paste this line directly into your browser bar:
35144
file://<removed>/wetostack/docs/_build/html/index.html
36-
37145
```
38-
Note that the docs/_build folder must be removed and a rebuild done if changes to the software_attributes/database/ yamls are made.
39-
40-
## Dependencies
41146
42-
The Python packages required to build this project, including those for the documentation site,
43-
are listed in `requirements.txt`.
147+
Note that the `docs/_build` folder must be removed and a rebuild completed if there are changes to
148+
the `software_attributes/database/` YAML files.
149+
150+
## Entry Guide Project Description
151+
152+
The Entry Guide project is built with [VueJS](https://vuejs.org) as a reactive front-end framework.
153+
The language is TypeScript and a VueJS domain-specific language that is essentially HTML.
154+
The Vue files have the `.vue` suffix and define the Vue components with three sections:
155+
156+
- script
157+
- template
158+
- style (optional)
159+
160+
The script section is TypeScript and defines the data and functions used to create the content
161+
laid out in the template section.
162+
The style section optionally contains CSS styling for the elements in the template section.
163+
164+
The app is structured as a main page with tabs that contain [VueFlow](https://vueflow.dev)
165+
canvases that render the graphs.
166+
The main entry point is `App.vue`, and it loads the tab elements and lays out the main page.
167+
The tab bar itself (the row of tab names on the main page) is described in `Tabs.vue`.
168+
The tab elements are defined in corresponding files in `tabs/`.
169+
The tab elements load their corresponding graph data from `data/` and then create their layout
170+
using the `layout` function from `Layout.ts` which uses [DagreJS](https://github.com/dagrejs/dagre)
171+
to systematically produce the layout.
172+
Some additional functionality for the graph reactivity is available in `utils.ts` and configured
173+
in the tab elements.
174+
All tabs are essentially the same code and structure but load a different data file.
175+
176+
The graph data are defined as nodes and edges.
177+
A node can be either a `type: decision` or `type: tool`.
178+
When the graph traversal routines reach a tool node, they stop traversing.
179+
Decision-type nodes have "a" and "b" attributes to provide the switch functionality.
180+
The edges must be defined as a source, target, and label.
181+
The source and target are node IDs, and the label is either `a` or `b` to denote which state
182+
of the switch activates the edge.
183+
184+
New tabs can be added by copying an existing tab and data file to new files.
185+
The data should be updated as appropriate.
186+
Then, the tab element should be imported in `App.vue` and added as an element to the
187+
`tabList` variable.
188+
From there, the app should include the new tab in the existing structure.
44189
45190
## License
46191
47-
WETO Software Stack is licensed under Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International
192+
WETO Software Stack is licensed under
193+
Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International

0 commit comments

Comments
 (0)