Skip to content

Commit 0c1d292

Browse files
d-ryan-ashcraftd-ryan-ashcraft
committed
#5 📝 documentation checkpoint
1 parent c9d668a commit 0c1d292

File tree

5 files changed

+388
-8
lines changed

5 files changed

+388
-8
lines changed

‎.github/workflows/publish.yml

+34-8
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,50 @@
11
name: Publish to GitHub Pages
2+
23
on:
4+
# Allows you to run this workflow manually from the Actions tab
35
workflow_dispatch:
6+
7+
# Runs on pushes targeting the following branch(es)
48
push:
5-
branches: [dev]
9+
branches: [5-migrate-documentation]
10+
11+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19+
concurrency:
20+
group: "pages"
21+
cancel-in-progress: false
22+
623
jobs:
7-
build:
24+
# Single deploy job since we're just deploying
25+
deploy:
26+
environment:
27+
name: github-pages
28+
url: ${{ steps.deployment.outputs.page_url }}
829
runs-on: ubuntu-latest
930
steps:
1031
- name: Checkout repository
11-
uses: actions/checkout@v2
32+
uses: actions/checkout@v4
33+
- name: Setup Pages
34+
uses: actions/configure-pages@v5
1235
- name: Install Node.js
1336
uses: actions/setup-node@v2
1437
with:
15-
node-version: '16'
38+
node-version: '20'
1639
- name: Install Antora
1740
run: npm i antora
1841
- name: Generate Site
1942
run: GIT_CREDENTIALS="https://${{ secrets.PAT }}:@github.com" npx antora docs/antora-playbook.yml
20-
- name: Publish to GitHub Pages
21-
uses: peaceiris/actions-gh-pages@v3
43+
- name: Upload artifact
44+
uses: actions/upload-pages-artifact@v3
2245
with:
23-
github_token: ${{ secrets.GITHUB_TOKEN }}
24-
publish_dir: docs/build/site
46+
# Upload entire repository
47+
path: docs/build/site
48+
- name: Deploy to GitHub Pages
49+
id: deployment
50+
uses: actions/deploy-pages@v4

‎docs/modules/ROOT/pages/archetype.adoc

+142
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
= Creating a Project
2+
3+
== Mapping to aiSSEMBLE(TM) Concepts
4+
[#img-you-are-here-archetype]
5+
.xref:solution-baseline-process.adoc[You Are Here]
6+
image::you-are-here-archetype.png[You Are Here,200,100,role="thumb right"]
7+
8+
_Step 1: Instantiate a New aiSSEMBLE Project:_ The aiSSEMBLE archetype is an executable pattern that can quickly incept
9+
a project that is ready to leverage aiSSEMBLE for constructing components tailored to your needs. It is realized below
10+
using a Maven archetype feature.
11+
12+
== Use a Maven Archetype to Create a New Project
13+
The first step in creating a new project is to leverage Maven's archetype functionality to incept a new Maven project
14+
that will contain all of your aiSSEMBLE component implementations - data delivery and machine learning pipelines as well as
15+
path to production modules.
16+
17+
Open a terminal to the location in which you want your project to live and execute the following command:
18+
[source]
19+
[subs=attributes+]
20+
21+
ifeval::[{is-pre-release} == true]
22+
--
23+
mvn archetype:generate \
24+
-DarchetypeGroupId=com.boozallen.aissemble \
25+
-DarchetypeArtifactId=foundation-archetype \
26+
-DarchetypeVersion={page-version}-SNAPSHOT
27+
--
28+
endif::[]
29+
30+
ifeval::[{is-pre-release} != true]
31+
--
32+
mvn archetype:generate \
33+
-DarchetypeGroupId=com.boozallen.aissemble \
34+
-DarchetypeArtifactId=foundation-archetype \
35+
-DarchetypeVersion={page-version}
36+
--
37+
endif::[]
38+
39+
This command will trigger an interactive questionnaire giving you the opportunity to enter the following information
40+
(in alphabetical order) except if the option is not interactive (see table). For those options that are not interactive, they must be supplied to the ``mvn
41+
archetype:generate`` command by using the following format ``-D<propertyName>=<propertyValue>``. For those options that are interactive,
42+
there is also an option to supply the values in the same way.
43+
44+
.Archetype Options
45+
[cols="1a,2a,3a,2a,5a"]
46+
|===
47+
| Value | Description | Guidance | Example(s) | Interactive
48+
49+
| ``archetypeVersion``
50+
| Use an archetype from a specific aiSSEMBLE release
51+
|
52+
Typically, developers should target the most recently released archetype. In appropriate circumstances, it is possible to target a pre-release https://maven.apache.org/guides/getting-started/index.html#what-is-a-snapshot-version[snapshot version,role=external,window=_blank] by using the -SNAPSHOT suffix.
53+
54+
|
55+
* 0.11.0
56+
* 0.9.8
57+
* 0.12.0-SNAPSHOT
58+
| No
59+
60+
| ``artifactId``
61+
| The folder name as well as module name of your project root
62+
| A generic description of the project or set of pipelines that will be included in the project. Maven conventions
63+
suggest the use of a dash to separate terms.
64+
|
65+
* ``payment-analytics``
66+
* ``charge-off-prediction``
67+
* ``rdec`` (example of a project acronym)
68+
| Yes
69+
70+
| ``groupId``
71+
| The namespace in which your Maven modules will live
72+
| In general, you want it to think about ``groupId`` like the notional reverse ordered internet address of your effort.
73+
General pattern: ``<internet domain name in reverse>.<your area name>``
74+
75+
| Examples:
76+
77+
* ``com.boozallen.aissemble``
78+
* ``mil.navy.blueangles.ridealong``
79+
80+
| Yes
81+
82+
| ``package``
83+
| The package name in which JVM-based source code will be placed
84+
| Defaults to your ``groupId`` value, which is almost always the right decision, so just select enter to accept this
85+
default
86+
| See ``groupId`` examples above
87+
| Yes
88+
89+
| ``projectDescription``
90+
| General description of your project
91+
| Default to "Project that contains aiSSEMBLE compliant pipeline(s)"
92+
|
93+
| No
94+
95+
| ``licenseName``
96+
| The name of the license to use in the project
97+
| Defaults to Booz Allen's "closed-source-license" but can be updated to a
98+
https://github.com/boozallen/booz-allen-maven-licenses[Booz Allen license,role=external,window=_blank] or any license
99+
under mvn license:license-list
100+
|
101+
* booz-allen-public-license
102+
* agpl_v3
103+
104+
| No
105+
106+
| ``projectGitUrl``
107+
| The git URL of the project
108+
| The git URL of the project, without the `.git` suffix
109+
|
110+
111+
112+
| Yes
113+
114+
| ``projectName``
115+
| A short, human-readable version name of the project
116+
| The human readable version of your ``artifactId``
117+
|
118+
119+
* aiSSEMBLE
120+
* NAVY BA Ride Along
121+
122+
| Yes
123+
124+
| ``version``
125+
| The name of the current version
126+
| Generally recommended to follow a ``<major version>.<minor version>.<patch version>`` convention. If you don't have a
127+
strong opinion, start at ``1.0.0-SNAPSHOT``. ``1.0.0-SNAPSHOT`` is the default when instantiating a new project.
128+
129+
Maven has inherent support for "development" versions. This helps projects manage in flight versus released software.
130+
See <<_snapshot_versions,Snapshot Versions>> in the Additional Considerations section below for more information. Using
131+
https://github.com/TechnologyBrewery/habushu[Habushu,role=external,window=_blank], python modules are able to easily
132+
and automatically follow this Snapshot pattern as well (where ``-SNAPSHOT`` will be inferred to ``.dev``.
133+
|
134+
* ``1.0.0-SNAPSHOT``
135+
* ``1.1.0-SNAPSHOT``
136+
137+
| No
138+
139+
|===
140+
141+
Once you enter these values, the archetype will ask you to confirm your entries. You now have a Maven project in which
142+
you can setup your specific pipelines, as described in the next step.

‎docs/modules/ROOT/pages/configurations.adoc

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
= Configuring Your Environment
2+
3+
== aiSSEMBLE(TM) Tooling
4+
The tools and configurations below are required to run aiSSEMBLE.
5+
6+
=== Build/Local Deployment Configurations
7+
8+
* Java: https://adoptium.net/temurin/archive/?version=11[JDK 11,role=external,window=_blank]
9+
(see the https://whichjdk.com/[following discussion,role=external,window=_blank] to choose between different JDKs)
10+
* Python: Python 3.11.4+ (we recommend using https://github.com/pyenv/pyenv[pyenv,role=external,window=_blank])
11+
* Build Process: https://maven.apache.org/[Maven,role=external,window=_blank] (see the
12+
xref:maven-configuration.adoc[Maven configuration] page for detailed instructions)
13+
* Docker and Kubernetes:
14+
** https://rancherdesktop.io/[Rancher Desktop,role=external,window=_blank] supports both Docker and Kubernetes
15+
** It conveniently allows a Docker repository to be used for both, which saves time and disk space locally
16+
* Continuous Deployment: https://docs.tilt.dev/install.html[Tilt,role=external,window=_blank] for local development
17+
* Source Code Management: https://git-scm.com/[git,role=external,window=_blank]
18+
19+
== Windows (WSL) Compatibility [[WSL]]
20+
Using aiSSEMBLE on Windows is only supported through Windows Subsystem for Linux (WSL). The following sections will
21+
guide you through configuring WSL.
22+
23+
=== Installing Ubuntu via Windows Subsystem for Linux v2
24+
25+
. Install Ubuntu via the Windows Subsystem for Linux v2
26+
** Utilizing PowerShell, execute the following commands:
27+
*** `wsl --install -d Ubuntu`
28+
*** `wsl --set-version Ubuntu 2`
29+
30+
=== Installing and Configuring Rancher Desktop
31+
. Install https://rancherdesktop.io/[Rancher Desktop,role=external,window=_blank].
32+
. Run Rancher Desktop
33+
. Select the newest stable version of Kubernetes.
34+
. Choose dockerd (moby).
35+
. In Rancher Desktop, select:
36+
.. File -> Preferences -> WSL
37+
.. Select the Ubuntu instance installed in the previous step.
38+
39+
[NOTE]
40+
=====
41+
Your WSL environment should be prepared now.
42+
43+
** *NOTE:* you can access your Windows files in WSL at `/mnt/<drive-letter>/<path>/<on>/<windows>`
44+
*** _Example:_ `/mnt/c/Users/MyUser/Downloads`

‎docs/modules/ROOT/pages/index.adoc

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
[NOTE]
2+
April 30, 2024: We are rolling out our documentation actively. You may find these pages incomplete or missing links
3+
until this process is completed. Please see https://github.com/boozallen/aissemble/issues/5[the associated
4+
GitHub issue,role=external,window=_blank] for more information.
5+
6+
= aiSSEMBLE(TM) User Manual
7+
8+
== Key Terms
9+
* **aiSSEMBLE** – (pronounced assemble) is Booz Allen’s lean, manufacturing-inspired approach for holistically designing,
10+
developing, and fielding AI solutions across the engineering lifecycle: from data processing (DataOps) to model building,
11+
tuning, and training (ModelOps, MLOps), to secure operational deployment (DevSecOps).
12+
* **https://github.com/boozallen/aissemble[Solution Baseline,role=external,window=_blank]** - An evolving,
13+
versioned, core set of capabilities that can serve as an implementation's foundation, enabling the rapid standup of an
14+
operational data delivery, data preparation, and/or machine learning (ML) pipelines.
15+
16+
== aiSSEMBLE Overview
17+
[.lead]
18+
The aiSSEMBLE Solution Baseline is an accelerant that helps AI projects by leveraging pre-packaged and tailored
19+
components, allowing a shift in focus towards value-added tasks, rather than labor-intensive, boilerplate tasks.
20+
21+
The Solution Baseline also lowers the barrier for including features that are otherwise treated as nice-to-have items,
22+
as teams often do not have time to incorporate them (e.g., drift detection, bias detection, provenance capture).
23+
24+
The Solution Baseline is the key enabler for the aiSSEMBLE manufacturing process: a modern take on a holistic,
25+
integrated lean software manufacturing process that can deliver a variety of AI products at high velocity. The graphic
26+
below demonstrates the steps to kick off an aiSSEMBLE project.
27+
28+
// .aiSSEMBLE Notional Architecture
29+
image::solution-baseline-process-overview.png[align="center",alt="Solution Baseline Overview",width=1366,height=768]
30+
31+
32+
== New project with aiSSEMBLE
33+
Getting started with aiSSEMBLE is easy! Once you have xref:configurations.adoc[configured your environment],
34+
create your first xref:archetype.adoc[new aiSSEMBLE project] by following our Getting Started guide.

0 commit comments

Comments
 (0)