Skip to content

Commit 72aa1a9

Browse files
CarkHTCarkHT
committed
more copy
1 parent 1182ba3 commit 72aa1a9

7 files changed

Lines changed: 2104 additions & 0 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
schedule:
8+
- cron: "0 0 * * *"
9+
pull_request:
10+
branches:
11+
- main
12+
workflow_dispatch:
13+
14+
env:
15+
POETRY_VERSION: "1.8.2"
16+
17+
jobs:
18+
docs:
19+
name: Build and Deploy to GitHub Pages
20+
runs-on: ubuntu-latest
21+
permissions:
22+
contents: write
23+
id-token: write
24+
packages: write
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0
30+
31+
- name: Set up Python
32+
uses: actions/setup-python@v5
33+
with:
34+
python-version: 3.11
35+
36+
- name: Load cached Poetry installation
37+
id: cache-poetry
38+
uses: actions/cache@v4
39+
with:
40+
path: ~/.local
41+
key: poetry-${{ env.POETRY_VERSION }}-${{ runner.os }}
42+
43+
- name: Install Poetry
44+
if: steps.cache-poetry.outputs.cache-hit != 'true'
45+
uses: snok/install-poetry@v1
46+
with:
47+
version: ${{ env.POETRY_VERSION }}
48+
49+
- name: Load cached venv
50+
id: cache-dependencies
51+
uses: actions/cache@v4
52+
with:
53+
path: .venv
54+
key: venv-py3.11-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
55+
56+
- name: Install dependencies
57+
if: steps.cache-dependencies.outputs.cache-hit != 'true'
58+
run: poetry install --no-interaction --no-root
59+
60+
- name: Install project
61+
run: poetry install --no-interaction
62+
63+
- name: Build docs
64+
id: build-docs
65+
if: github.event_name != 'push' || github.ref_name != github.event.repository.default_branch
66+
env:
67+
API_KEY: ${{ secrets.API_KEY_2 }}
68+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
69+
run: poetry run mkdocs build
70+
71+
- name: Upload docs
72+
uses: actions/upload-artifact@v4
73+
if: steps.build-docs.outcome == 'success'
74+
with:
75+
name: docs
76+
path: ./site
77+
if-no-files-found: error
78+
79+
- name: Deploy docs
80+
if: github.event_name == 'push' && github.ref_name == github.event.repository.default_branch
81+
env:
82+
API_KEY: ${{ secrets.API_KEY_2 }}
83+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
84+
ENABLE_EVALDOCS: true
85+
run: poetry run mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.env
2+
.DS_Store
3+
4+
.venv/
5+
venv/
6+
env/
7+
8+
site/

‎README.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Lambda Feedback User Documentation
2+
3+
This repository contains the user documentation for the Lambda Feedback platform. The documentation is built using [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/) and is hosted on [GitHub Pages](https://lambda-feedback.github.io/user-documentation/).
4+
5+
## Usage
6+
7+
This section guides you through the installation of the necessary dependencies and how to serve and build the documentation locally.
8+
9+
### Pre-requisites
10+
11+
- [Python 3.11](https://www.python.org/downloads/) or higher
12+
- [Poetry](https://python-poetry.org/docs/#installation)
13+
14+
### Installation
15+
16+
To serve or build the documentation locally, you have to install its dependencies. The documentation mainly builds on the following libraries:
17+
18+
- [MkDocs](https://www.mkdocs.org/getting-started/)
19+
- [MkDocs-Material](https://squidfunk.github.io/mkdocs-material/getting-started/)
20+
- [EvalDocsLoader](https://github.com/lambda-feedback/EvalDocsLoader)
21+
22+
To install the dependencies using Poetry, run the following command:
23+
24+
```bash
25+
poetry install
26+
```
27+
28+
### Serving the Documentation
29+
30+
To serve the documentation locally, run the following command:
31+
32+
```bash
33+
poetry run mkdocs serve
34+
```
35+
36+
This will start a local server at `http://127.0.0.1:8000/user-documentation/` where you can view the documentation.
37+
38+
> [!NOTE]
39+
> You can ignore warnings or errors related to the EvalDocsLoader plugin, as long as you do not want to load external documentation pages for evaluation functions.
40+
41+
### Building the Documentation
42+
43+
To build the documentation, run the following command:
44+
45+
```bash
46+
poetry run mkdocs build
47+
```
48+
49+
This will build the documentation in the `site` directory.
50+
51+
### Fetching Evaluation Function Documentation
52+
53+
To fetch the documentation for evaluation functions, the `EvalDocsLoader` plugin is used. The plugin is already installed as a dependency in the `pyproject.toml` file.
54+
55+
When the necessary environment variables are set, the plugin will fetch the documentation for available evaluation functions automatically, and add them to the documentation.
56+
57+
The following environment variables are required:
58+
59+
- `API_KEY`: The API key for the lambda feedback API.
60+
- `GITHUB_TOKEN`: A [GitHub Private Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with the `repo` scope to fetch the documentation from evaluation function repositories.
61+
62+
To set the environment variables, you can use the `export` command in your terminal:
63+
64+
```bash
65+
export API_KEY="<your-api-key>"
66+
export GITHUB_TOKEN="<your-github-access-token>"
67+
```
68+
69+
After setting the environment variables, you can serve or build the documentation as described above.
70+
71+
## Deployment
72+
73+
The documentation is deployed to [GitHub Pages](https://pages.github.com/) using a GitHub Actions workflow. Deployment is done automatically after every commit to the `main` branch, as well as at midnight every day, UTC.
74+
75+
## Documentation Development
76+
77+
Some links you might find useful when authoring documentation content:
78+
79+
- [MkDocs Documentation](https://www.mkdocs.org/user-guide/writing-your-docs/#writing-your-docs)
80+
- [MkDocs-Material Documentation](https://squidfunk.github.io/mkdocs-material/reference/)
81+
- [MkDocs Macros Plugin](https://mkdocs-macros-plugin.readthedocs.io/en/latest/)

‎mkdocs.yml‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Project information
2+
site_name: Lambda Feedback Documentation
3+
site_author: Pierre Tharreau, Louis Manestar
4+
site_url: https://lambda-feedback.github.io/user-documentation/
5+
site_description: >-
6+
Architecture, syntax and usage details for an online learning platform
7+
focused on providing rich feedback to the user.
8+
repo_url: https://github.com/lambda-feedback/user-documentation
9+
edit_uri: blob/main/docs/
10+
11+
# Project tree
12+
nav:
13+
- Home:
14+
- "index.md"
15+
- Publications: "publications.md"
16+
- Opportunities: "opportunities.md"
17+
- Terminology: "terminology.md"
18+
- Releases:
19+
- Major releases: "releases/major_releases.md"
20+
- Detailed Releases: "releases/detailed_releases.md"
21+
- Previous releases:
22+
- 2023-24: "releases/relases_2023_24.md"
23+
- Status: "releases/status.md"
24+
25+
- Students:
26+
- "student/index.md"
27+
- Getting Started: "student/getting_started_student.md"
28+
- Answering Questions: "student/answering_questions.md"
29+
- Response Areas: "student/response_areas.md"
30+
- Text Editing: "student/lexdown_student.md"
31+
- FAQ: "student/faq.md"
32+
33+
- Teachers:
34+
- "teacher/index.md"
35+
- Guides:
36+
- Getting Started: "teacher/guides/gettingstarted.md"
37+
- Editing questions: "teacher/guides/content-sets-questions.md"
38+
- Exporting and importing questions: "teacher/guides/question-export-import.md"
39+
- Milkdown: "teacher/guides/lexdown.md"
40+
- Analytics: "teacher/guides/analytics.md"
41+
- Good practice: "teacher/guides/good-practice.md"
42+
- FAQ: "teacher/guides/faq.md"
43+
- Guidance:
44+
- Guidance Time Suggestion: "teacher/guides/guidance/guidance-time-suggestion.md"
45+
46+
- Reference:
47+
- Access control: "teacher/reference/access_control.md"
48+
- Latex functionality: "teacher/reference/latex_functionality.md"
49+
- PDF generation: "teacher/reference/pdf_generation.md"
50+
- Response Areas:
51+
- "teacher/reference/response_area_components/index.md"
52+
- Text: "teacher/reference/response_area_components/Text.md"
53+
- Number: "teacher/reference/response_area_components/Number.md"
54+
- Boolean: "teacher/reference/response_area_components/Boolean.md"
55+
- NumericUnits: "teacher/reference/response_area_components/NumericUnits.md"
56+
- Expression: "teacher/reference/response_area_components/Expression.md"
57+
- MultipleChoice: "teacher/reference/response_area_components/MultipleChoice.md"
58+
- Matrix: "teacher/reference/response_area_components/Matrix.md"
59+
- Table: "teacher/reference/response_area_components/Table.md"
60+
- Evaluation Functions:
61+
- "teacher/reference/evaluation_functions/index.md"
62+
63+
- Advanced:
64+
- "advanced/index.md"
65+
- Response Areas:
66+
- Overview: "advanced/response_areas/overview.md"
67+
- Evaluation Functions:
68+
- Quickstart Guide: "advanced/evaluation_functions/quickstart.md"
69+
- General Specification: "advanced/evaluation_functions/specification.md"
70+
- Feedback: "advanced/evaluation_functions/feedback.md"
71+
- Testing Functions Locally: "advanced/evaluation_functions/local.md"
72+
- Evaluation Function Utils: "advanced/evaluation_functions/module.md"
73+
- Deployed Functions:
74+
- "advanced/evaluation_functions/index.md"
75+
- Alternate Function Languages: "advanced/evaluation_functions/alternate_languages.md"
76+
- Chat functions:
77+
- Quickstart: "advanced/chat_functions/quickstart.md"
78+
- Testing Functions Locally: "advanced/chat_functions/local.md"
79+
80+
# Configuration
81+
theme:
82+
name: material
83+
logo: assets/logo.png
84+
favicon: assets/favicon.png
85+
icon:
86+
repo: fontawesome/brands/github
87+
edit: fontawesome/solid/pen-to-square
88+
features:
89+
- navigation.indexes
90+
- navigation.instant
91+
- navigation.sections
92+
#- navigation.top
93+
- navigation.tabs
94+
- navigation.tabs.sticky
95+
- content.action.edit
96+
- content.code.copy
97+
palette:
98+
- media: "(prefers-color-scheme: light)"
99+
scheme: default
100+
toggle:
101+
icon: material/weather-sunny
102+
name: Switch to dark mode
103+
- media: "(prefers-color-scheme: dark)"
104+
scheme: slate
105+
primary: indigo
106+
accent: indigo
107+
toggle:
108+
icon: material/weather-night
109+
name: Switch to light mode
110+
111+
# Extensions
112+
markdown_extensions:
113+
- toc:
114+
permalink: true
115+
- admonition
116+
- def_list
117+
- pymdownx.highlight
118+
- pymdownx.superfences
119+
- pymdownx.details
120+
- pymdownx.emoji:
121+
emoji_index: !!python/name:material.extensions.emoji.twemoji
122+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
123+
- pymdownx.arithmatex:
124+
generic: true
125+
- attr_list
126+
- md_in_html
127+
# - meta
128+
- tables
129+
130+
extra_javascript:
131+
- scripts/mathjax.js
132+
- https://polyfill.io/v3/polyfill.min.js?features=es6
133+
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
134+
135+
# Plugins
136+
plugins:
137+
- search
138+
- git-revision-date-localized:
139+
fallback_to_build_date: true
140+
- macros
141+
- evaldocsloader:
142+
enabled: !ENV [ENABLE_EVALDOCS, true]
143+
functions_announce_endpoint: "https://prod-api.lambdafeedback.com/evaluation-functions/registered"
144+
api_key:
145+
!ENV [
146+
API_KEY,
147+
"WiOS1vMpQyTuGL06ZJxjG1eZd2P0SPvuVzHpr6zjkTIJ33U2t5O5NWaZboWBv8aV",
148+
]
149+
dev_section: ["Advanced", "Evaluation Functions", "Deployed Functions"]
150+
user_section: ["Teachers", "Reference", "Evaluation Functions"]
151+
github_token: !ENV [GITHUB_TOKEN, ""]
152+
153+
# Extra variables, accessible within markdown pages
154+
extra:
155+
urls:
156+
client: https://lambdafeedback.com

0 commit comments

Comments
 (0)