Skip to content

Commit 08aa591

Browse files
dbirmandbirman
committed
docs: overhaul top-level
1 parent a7b718f commit 08aa591

37 files changed

Lines changed: 379 additions & 597 deletions

‎.github/workflows/tag_and_publish.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ on:
88
# Requires that svc-aindscicomp be added as an admin to repo.
99
jobs:
1010
tag:
11-
if: ${{github.event.repository.name == 'scicomp-docs'}}
11+
if: ${{github.event.repository.name == 'aind-software-docs'}}
1212
uses: AllenNeuralDynamics/aind-github-actions/.github/workflows/tag.yml@main
1313
secrets:
1414
SERVICE_TOKEN: ${{ secrets.SERVICE_TOKEN }}

‎README.md‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,11 @@ Please read: https://docs.allenneuraldynamics.org/en/latest/docs.html
66

77
## Development
88

9-
To generate the rst files source files for the documentation locally, run
9+
To re-build the documentation, from the `docs/` directory:
1010

1111
```bash
12-
sphinx-apidoc -o docs/source/ src
13-
```
14-
15-
Then to create the documentation HTML files, run
16-
17-
```bash
18-
sphinx-build -b html docs/source/ docs/build/html
12+
make clean
13+
make html
1914
```
2015

2116
More info on sphinx installation can be found [here](https://www.sphinx-doc.org/en/master/usage/installation.html).

‎docs/source/_static/aind-software-overview.png‎

5.29 MB
Loading

‎docs/source/about.md‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎docs/source/acquire_upload.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Acquire and upload data
2+
3+
## I want to...
4+
5+
[Prepare my metadata](acquire_upload/prepare_before_acquisition.md) before acquisition.
6+
7+
[Run my acquisition](acquire_upload/on_rig.md) on a rig.
8+
9+
[Upload my data assets](acquire_upload/upload.md) to the Cloud.
10+
11+
```{toctree}
12+
:hidden:
13+
14+
acquire_upload/prepare_before_acquisition
15+
acquire_upload/on_rig
16+
acquire_upload/upload
17+
```

‎docs/source/acquire_upload/on_rig.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# On rig
2+
3+
[TODO]

‎docs/source/acquire_upload/prepare_before_acquisition.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
# Prepare metadata
2+
3+
Before running an acquisition, you are responsible for ensuring that your **project metadata**, **instrument**, and **procedures** are valid and accessible through the metadata-service.
4+
5+
## Project name
6+
7+
Your *project* and *subproject* (if applicable) as well as funding information and investigators need to be accurate.
8+
9+
You can find a list of project names and combined "<project_name> - <subproject_name>" names at this [metadata-service endpoint](http://aind-metadata-service/api/v2/project_names). These are the only allowable project names available at this time.
10+
11+
If you need a new project name, it needs to be added to the [project metadata smartsheet](https://app.smartsheet.com/b/login?dlp=%2Fsheets%2FR4GfCrXvHPJ5MjhjRvjgGRMJQxvwQg92wgcX5GP1).
12+
13+
### Funding
14+
15+
The funding endpoint will be used during data upload to populate your data description with funding information. Please check that your funding information is accurate in advance:
16+
17+
```{raw} html
18+
<div style="margin: 20px 0; padding: 15px; border: 1px solid #ccc; border-radius: 5px; background-color: #f9f9f9;">
19+
<label for="projectSelect" style="font-weight: bold; display: block; margin-bottom: 10px;">Select a project fetch funding information from the metadata-service:</label>
20+
<select id="projectSelect" style="width: 100%; padding: 8px; margin-bottom: 10px; border: 1px solid #ccc; border-radius: 4px;">
21+
<option value="">-- Loading projects... --</option>
22+
</select>
23+
<button id="submitBtn" style="padding: 8px 20px; background-color: #007bff; color: white; border: none; border-radius: 4px; cursor: pointer; font-weight: bold;">Get Funding Info</button>
24+
<div id="fundingResult" style="margin-top: 15px; padding: 10px; border-radius: 4px; display: none;"></div>
25+
</div>
26+
27+
<script type="text/javascript">
28+
(function() {
29+
const select = document.getElementById('projectSelect');
30+
const submitBtn = document.getElementById('submitBtn');
31+
const resultDiv = document.getElementById('fundingResult');
32+
33+
// Try to fetch project names - will fail if not on VPN
34+
fetch('http://aind-metadata-service/api/v2/project_names')
35+
.then(response => {
36+
if (!response.ok) throw new Error('Service not accessible');
37+
return response.json();
38+
})
39+
.then(data => {
40+
select.innerHTML = '<option value="">-- Select a project --</option>';
41+
data.forEach(project => {
42+
const option = document.createElement('option');
43+
option.value = project;
44+
option.textContent = project;
45+
select.appendChild(option);
46+
});
47+
})
48+
.catch(error => {
49+
select.innerHTML = '<option value="">Service unavailable</option>';
50+
select.disabled = true;
51+
submitBtn.disabled = true;
52+
submitBtn.style.opacity = '0.5';
53+
submitBtn.style.cursor = 'not-allowed';
54+
resultDiv.style.display = 'block';
55+
resultDiv.style.backgroundColor = '#fff3cd';
56+
resultDiv.style.border = '1px solid #ffc107';
57+
resultDiv.innerHTML = '<strong>Please access the docs on the Allen Institute network to preview metadata</strong>';
58+
console.error('Metadata service not accessible:', error);
59+
});
60+
61+
// Handle submit button click
62+
document.getElementById('submitBtn').addEventListener('click', function() {
63+
const projectName = document.getElementById('projectSelect').value;
64+
const resultDiv = document.getElementById('fundingResult');
65+
66+
if (!projectName) {
67+
resultDiv.style.display = 'block';
68+
resultDiv.style.backgroundColor = '#fff3cd';
69+
resultDiv.style.border = '1px solid #ffc107';
70+
resultDiv.innerHTML = '<strong>Please select a project first.</strong>';
71+
return;
72+
}
73+
74+
resultDiv.style.display = 'block';
75+
resultDiv.style.backgroundColor = '#e7f3ff';
76+
resultDiv.style.border = '1px solid #0066cc';
77+
resultDiv.innerHTML = '<strong>Loading...</strong>';
78+
79+
fetch('http://aind-metadata-service/api/v2/funding/' + encodeURIComponent(projectName))
80+
.then(response => {
81+
if (!response.ok) {
82+
throw new Error('HTTP error! status: ' + response.status);
83+
}
84+
return response.json();
85+
})
86+
.then(response => {
87+
const data = response.data || response;
88+
resultDiv.style.backgroundColor = '#d4edda';
89+
resultDiv.style.border = '1px solid #28a745';
90+
resultDiv.innerHTML = '<strong>Funding Information:</strong><pre style="margin-top: 10px; white-space: pre-wrap; word-wrap: break-word;">' +
91+
JSON.stringify(data, null, 2) + '</pre>';
92+
})
93+
.catch(error => {
94+
resultDiv.style.backgroundColor = '#f8d7da';
95+
resultDiv.style.border = '1px solid #dc3545';
96+
resultDiv.innerHTML = '<strong>Error:</strong> ' + error.message;
97+
console.error('Error fetching funding info:', error);
98+
});
99+
});
100+
})();
101+
</script>
102+
```
103+
104+
### Investigators
105+
106+
The investigators endpoint will be used during data upload to populate your data description with investigator information. Please check that your investigator information is accurate in advance:
107+
108+
```{raw} html
109+
<div style="margin: 20px 0; padding: 15px; border: 1px solid #ccc; border-radius: 5px; background-color: #f9f9f9;">
110+
<label for="projectSelectInvestigators" style="font-weight: bold; display: block; margin-bottom: 10px;">Select a project to fetch investigator information from the metadata-service:</label>
111+
<select id="projectSelectInvestigators" style="width: 100%; padding: 8px; margin-bottom: 10px; border: 1px solid #ccc; border-radius: 4px;">
112+
<option value="">-- Loading projects... --</option>
113+
</select>
114+
<button id="submitBtnInvestigators" style="padding: 8px 20px; background-color: #007bff; color: white; border: none; border-radius: 4px; cursor: pointer; font-weight: bold;">Get Investigator Info</button>
115+
<div id="investigatorResult" style="margin-top: 15px; padding: 10px; border-radius: 4px; display: none;"></div>
116+
</div>
117+
118+
<script type="text/javascript">
119+
(function() {
120+
const select = document.getElementById('projectSelectInvestigators');
121+
const submitBtn = document.getElementById('submitBtnInvestigators');
122+
const resultDiv = document.getElementById('investigatorResult');
123+
124+
// Try to fetch project names - will fail if not on VPN
125+
fetch('http://aind-metadata-service/api/v2/project_names')
126+
.then(response => {
127+
if (!response.ok) throw new Error('Service not accessible');
128+
return response.json();
129+
})
130+
.then(data => {
131+
select.innerHTML = '<option value="">-- Select a project --</option>';
132+
data.forEach(project => {
133+
const option = document.createElement('option');
134+
option.value = project;
135+
option.textContent = project;
136+
select.appendChild(option);
137+
});
138+
})
139+
.catch(error => {
140+
select.innerHTML = '<option value="">Service unavailable</option>';
141+
select.disabled = true;
142+
submitBtn.disabled = true;
143+
submitBtn.style.opacity = '0.5';
144+
submitBtn.style.cursor = 'not-allowed';
145+
resultDiv.style.display = 'block';
146+
resultDiv.style.backgroundColor = '#fff3cd';
147+
resultDiv.style.border = '1px solid #ffc107';
148+
resultDiv.innerHTML = '<strong>Please access the docs on the Allen Institute network to preview metadata</strong>';
149+
console.error('Metadata service not accessible:', error);
150+
});
151+
152+
// Handle submit button click
153+
document.getElementById('submitBtnInvestigators').addEventListener('click', function() {
154+
const projectName = document.getElementById('projectSelectInvestigators').value;
155+
const resultDiv = document.getElementById('investigatorResult');
156+
157+
if (!projectName) {
158+
resultDiv.style.display = 'block';
159+
resultDiv.style.backgroundColor = '#fff3cd';
160+
resultDiv.style.border = '1px solid #ffc107';
161+
resultDiv.innerHTML = '<strong>Please select a project first.</strong>';
162+
return;
163+
}
164+
165+
resultDiv.style.display = 'block';
166+
resultDiv.style.backgroundColor = '#e7f3ff';
167+
resultDiv.style.border = '1px solid #0066cc';
168+
resultDiv.innerHTML = '<strong>Loading...</strong>';
169+
170+
fetch('http://aind-metadata-service/api/v2/investigators/' + encodeURIComponent(projectName))
171+
.then(response => {
172+
if (!response.ok) {
173+
throw new Error('HTTP error! status: ' + response.status);
174+
}
175+
return response.json();
176+
})
177+
.then(response => {
178+
const data = response.data || response;
179+
resultDiv.style.backgroundColor = '#d4edda';
180+
resultDiv.style.border = '1px solid #28a745';
181+
resultDiv.innerHTML = '<strong>Investigator Information:</strong><pre style="margin-top: 10px; white-space: pre-wrap; word-wrap: break-word;">' +
182+
JSON.stringify(data, null, 2) + '</pre>';
183+
})
184+
.catch(error => {
185+
resultDiv.style.backgroundColor = '#f8d7da';
186+
resultDiv.style.border = '1px solid #dc3545';
187+
resultDiv.innerHTML = '<strong>Error:</strong> ' + error.message;
188+
console.error('Error fetching investigator info:', error);
189+
});
190+
});
191+
})();
192+
</script>
193+
```
194+
195+
## Instrument
196+
197+
[Instrument](https://aind-data-schema.readthedocs.io/en/latest/instrument.html) metadata should be prepared in advance and uploaded to the metadata-service.
198+
199+
Keep track of your `instrument_id` you will need to provide this value when you upload your data asset later.
200+
201+
### I want to write an instrument.json
202+
203+
### I'm ready to upload my instrument.json
204+
205+
[TODO]
206+
207+
## Procedures
208+
209+
[Procedures](https://aind-data-schema.readthedocs.io/en/latest/procedures.html) metadata should be prepared in advance and uploaded to the metadata-service.
210+
211+
Standardized procedures that are performed by NSB (link?) are uploaded and accessible through the metadata-service. You can see the available procedures for a mouse by passing its subject_id here:
212+
213+
```{raw} html
214+
<div style="margin: 20px 0; padding: 15px; border: 1px solid #ccc; border-radius: 5px; background-color: #f9f9f9;">
215+
<label for="subjectIdInput" style="font-weight: bold; display: block; margin-bottom: 10px;">Enter a subject ID to fetch procedures from the metadata-service:</label>
216+
<input type="text" id="subjectIdInput" placeholder="e.g., 804670" style="width: 100%; padding: 8px; margin-bottom: 10px; border: 1px solid #ccc; border-radius: 4px;">
217+
<button id="submitBtnProcedures" style="padding: 8px 20px; background-color: #007bff; color: white; border: none; border-radius: 4px; cursor: pointer; font-weight: bold;">Get Procedures</button>
218+
<div id="proceduresResult" style="margin-top: 15px; padding: 10px; border-radius: 4px; display: none;"></div>
219+
</div>
220+
221+
<script type="text/javascript">
222+
(function() {
223+
const subjectInput = document.getElementById('subjectIdInput');
224+
const submitBtn = document.getElementById('submitBtnProcedures');
225+
const resultDiv = document.getElementById('proceduresResult');
226+
227+
// Try to fetch project names to check if service is accessible
228+
fetch('http://aind-metadata-service/api/v2/project_names')
229+
.then(response => {
230+
if (!response.ok) throw new Error('Service not accessible');
231+
return response.json();
232+
})
233+
.then(data => {
234+
// Service is accessible, widget is ready
235+
})
236+
.catch(error => {
237+
subjectInput.disabled = true;
238+
subjectInput.placeholder = 'Service unavailable';
239+
submitBtn.disabled = true;
240+
submitBtn.style.opacity = '0.5';
241+
submitBtn.style.cursor = 'not-allowed';
242+
resultDiv.style.display = 'block';
243+
resultDiv.style.backgroundColor = '#fff3cd';
244+
resultDiv.style.border = '1px solid #ffc107';
245+
resultDiv.innerHTML = '<strong>Please access the docs on the Allen Institute network to preview metadata</strong>';
246+
console.error('Metadata service not accessible:', error);
247+
});
248+
249+
// Handle submit button click
250+
document.getElementById('submitBtnProcedures').addEventListener('click', function() {
251+
const subjectId = document.getElementById('subjectIdInput').value.trim();
252+
const resultDiv = document.getElementById('proceduresResult');
253+
254+
if (!subjectId) {
255+
resultDiv.style.display = 'block';
256+
resultDiv.style.backgroundColor = '#fff3cd';
257+
resultDiv.style.border = '1px solid #ffc107';
258+
resultDiv.innerHTML = '<strong>Please enter a subject ID.</strong>';
259+
return;
260+
}
261+
262+
resultDiv.style.display = 'block';
263+
resultDiv.style.backgroundColor = '#e7f3ff';
264+
resultDiv.style.border = '1px solid #0066cc';
265+
resultDiv.innerHTML = '<strong>Loading procedures...</strong><br><em>This may take 30 seconds or more, please wait...</em>';
266+
267+
fetch('http://aind-metadata-service/api/v2/procedures/' + encodeURIComponent(subjectId))
268+
.then(response => {
269+
if (!response.ok) {
270+
throw new Error('HTTP error! status: ' + response.status);
271+
}
272+
return response.json();
273+
})
274+
.then(response => {
275+
const data = response.data || response;
276+
resultDiv.style.backgroundColor = '#d4edda';
277+
resultDiv.style.border = '1px solid #28a745';
278+
resultDiv.innerHTML = '<strong>Procedures Information:</strong><pre style="margin-top: 10px; white-space: pre-wrap; word-wrap: break-word;">' +
279+
JSON.stringify(data, null, 2) + '</pre>';
280+
})
281+
.catch(error => {
282+
resultDiv.style.backgroundColor = '#f8d7da';
283+
resultDiv.style.border = '1px solid #dc3545';
284+
resultDiv.innerHTML = '<strong>Error:</strong> ' + error.message;
285+
console.error('Error fetching procedures:', error);
286+
});
287+
});
288+
289+
// Allow Enter key to submit
290+
document.getElementById('subjectIdInput').addEventListener('keypress', function(event) {
291+
if (event.key === 'Enter') {
292+
document.getElementById('submitBtnProcedures').click();
293+
}
294+
});
295+
})();
296+
</script>
297+
```

‎docs/source/acquire_upload/upload.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Upload

‎docs/source/coding.md‎

Lines changed: 0 additions & 24 deletions
This file was deleted.

0 commit comments

Comments
 (0)