Skip to content

Commit 8315112

Browse files
henryborchershenryborchers
committed
docs: added documentation
1 parent fc8cfc7 commit 8315112

File tree

9 files changed

+320
-20
lines changed

9 files changed

+320
-20
lines changed

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = ../build/docs
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/conf.py‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
import os
7+
8+
try:
9+
from tomllib import loads as load_toml
10+
except ImportError:
11+
from toml import loads as load_toml
12+
13+
def get_project_metadata():
14+
path = os.path.abspath(os.path.join(os.path.dirname(__file__), "../pyproject.toml"))
15+
with open(path, "r") as f:
16+
return load_toml(f.read())['project']
17+
18+
metadata = get_project_metadata()
19+
20+
# -- Project information -----------------------------------------------------
21+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
22+
23+
project = metadata['name']
24+
copyright = f'2026, {metadata["authors"][0]["name"]}'
25+
author = metadata['authors'][0]['name']
26+
27+
# -- General configuration ---------------------------------------------------
28+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
29+
30+
extensions = [
31+
'sphinx.ext.doctest',
32+
'sphinxcontrib.spelling'
33+
]
34+
35+
templates_path = ['_templates']
36+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
37+
38+
39+
40+
# -- Options for HTML output -------------------------------------------------
41+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
42+
43+
html_theme = 'alabaster'
44+
html_static_path = [
45+
# '_static'
46+
]

‎docs/deployment.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
=========================
2+
Installing and Deployment
3+
=========================
4+
5+
This section provides instructions for deploying the application in a production environment.
6+
7+
In order to use the application, you need to create a configuration file as described below.
8+
9+
.. _configuration-file:
10+
11+
Configuration File
12+
==================
13+
14+
The application requires a configuration file in INI format. The configuration file should contain the following sections and options:
15+
16+
.. code-block:: ini
17+
18+
[ALMA_API]
19+
API_DOMAIN= ;url to ALMA's API endpoint
20+
API_KEY= ;API key for accessing ALMA's API
21+
22+
Using Docker Image for Deployment
23+
=================================
24+
25+
If a Docker image is available, you can deploy the application using Docker. And if not, you can build the Docker image
26+
locally using the provided `Dockerfile`. :ref:`See the Development section for instructions on building the Docker image.<dockerizing>`
27+
28+
If a docker image has been created locally, use the following command, ensuring to mount your configuration file and
29+
expose the necessary port:
30+
31+
.. code-block:: console
32+
33+
$ docker run -d -p 5000:5000 -v /path/to/your/settings.cfg:/app/settings.cfg:ro --name getmarc getmarcapi
34+
35+
By default, the container looks for the config file at `/app/settings.cfg` inside the container, but this can be
36+
changed by setting the `GETMARCAPI_SETTINGS` environment variable to another path.
37+
38+
The default port 5000 inside the container is used for the web server, so ensure this port is forwarded to the host
39+
machine.

‎docs/development.rst‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
===========
2+
Development
3+
===========
4+
5+
This section provides an overview of the development and deployment process for the project.
6+
7+
The application requires a configuration file in INI format. The configuration file format can be found in the
8+
:ref:`config file section <configuration-file>`.
9+
10+
Build for Production
11+
====================
12+
13+
.. _dockerizing:
14+
15+
Dockerizing the Application
16+
---------------------------
17+
To containerize the application using Docker, use the `Dockerfile` at the root of the project. You can build the Docker image with the following command:
18+
19+
.. code-block:: console
20+
21+
$ docker build -t getmarcapi .
22+
23+
24+
Run Locally for Development
25+
===========================
26+
27+
Prerequisites
28+
-------------
29+
Preinstalled Development dependencies:
30+
31+
* uv (manage Python e)
32+
* Node.js and npm (for building static assets)
33+
34+
.. Note::
35+
36+
You should be using `uv <https://docs.astral.sh/uv/>`_ to manage your virtual environments and dependencies. These
37+
directions are going to assume that you have uv installed. If you do not have
38+
`uv` installed, you *can* use `pip` but **uv is HIGHLY RECOMMENDED**.
39+
40+
`See uv installation instructions <https://docs.astral.sh/uv/getting-started/installation/>`_.
41+
42+
Getting Development Environment Set Up
43+
--------------------------------------
44+
45+
To run the application locally for development purposes, follow these steps:
46+
47+
1. Clone the repository:
48+
49+
.. code-block:: console
50+
51+
$ git clone https://github.com/UIUCLibrary/getmarcapi.git
52+
Cloning into 'getmarcapi'...
53+
remote: Enumerating objects: 986, done.
54+
remote: Counting objects: 100% (364/364), done.
55+
remote: Compressing objects: 100% (157/157), done.
56+
remote: Total 986 (delta 271), reused 210 (delta 207), pack-reused 622 (from 2)
57+
Receiving objects: 100% (986/986), 441.69 KiB | 7.36 MiB/s, done.
58+
Resolving deltas: 100% (468/468), done.
59+
60+
$ cd getmarcapi
61+
62+
2. Create and activate a Python virtual environment using uv with the development dependencies:
63+
64+
On Unix Environments:
65+
66+
.. code-block:: console
67+
68+
$ uv sync --dev
69+
Resolved 119 packages in 33ms
70+
Audited 106 packages in 46ms
71+
72+
$ source .venv/bin/activate
73+
74+
On Windows Environments:
75+
76+
.. code-block:: pwsh-session
77+
78+
> uv sync --dev
79+
Resolved 119 packages in 33ms
80+
Audited 106 packages in 46ms
81+
82+
> .venv\Scripts\activate
83+
84+
3. Gather and build the static assets:
85+
86+
There are some nice CSS libraries used in the top-level API documentation page. During development, you will need to
87+
install them to getmarcapi/static.
88+
89+
.. code-block:: console
90+
91+
(getmarcapi) $ npm install
92+
(getmarcapi) $ npm run env -- webpack --output-path=./getmarcapi/static
93+
94+
4. Start the Flask development server:
95+
96+
97+
.. code-block:: console
98+
99+
(getmarcapi) $ FLASK_APP=getmarcapi/app.py uv run flask run
100+
* Serving Flask app 'getmarcapi/app.py'
101+
* Debug mode: off
102+
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
103+
* Running on http://127.0.0.1:5000
104+
Press CTRL+C to quit
105+
106+
.. important::
107+
108+
You need to have the api url and api key.
109+
110+
For development, you can set the **ALMA_API_DOMAIN** and **API_KEY** environment variables in your shell.
111+
112+
113+
Running Tests
114+
=============
115+
116+
To run tests, you need to have pytest installed. If you are using the development environment, it should already be
117+
installed. Tests are run by executing the pytest command.
118+
119+
.. code-block:: shell-session
120+
121+
(getmarcapi) $ pytest
122+
============================== test session starts ==============================
123+
platform darwin -- Python 3.11.10, pytest-8.4.2, pluggy-1.6.0 -- .venv/bin/python
124+
cachedir: .pytest_cache
125+
rootdir: /Users/mydev/pythonprojects/getmarcapi
126+
configfile: pyproject.toml
127+
testpaths: tests
128+
plugins: anyio-4.12.1, typeguard-4.4.4
129+
collected 27 items
130+
131+
tests/test_api.py::test_root PASSED
132+
tests/test_api.py::test_get_record_xml PASSED
133+
tests/test_api.py::test_get_record_missing_param PASSED
134+
tests/test_api.py::test_api_documentation PASSED
135+
...
136+
============================== 27 passed in 0.34s ===============================

‎docs/index.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. d documentation master file, created by
2+
sphinx-quickstart on Thu Feb 5 08:36:50 2026.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
GetMarc API server documentation
7+
================================
8+
9+
GetMarc API is a web service that provides access to MARC records from the Alma library
10+
11+
.. toctree::
12+
:maxdepth: 2
13+
:caption: Contents:
14+
15+
deployment
16+
development

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=..\build\docs
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/spelling_wordlist.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
api
2+
config
3+
dockerizing
4+
getmarcapi
5+
js
6+
npm
7+
url
8+
uv

‎uv.lock‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎vars/runJenkinsPipeline.groovy‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -126,23 +126,23 @@ def call(){
126126
recordIssues(tools: [taskScanner(highTags: 'FIXME', includePattern: 'getmarcapi"F/**/*.py', normalTags: 'TODO')])
127127
}
128128
}
129-
// stage('Doctest'){
130-
// steps {
131-
// sh 'coverage run --parallel-mode --source getmarcapi -m sphinx -b doctest -d build/docs/doctrees docs reports/doctest -w logs/doctest.log'
132-
// }
133-
// post{
134-
// always {
135-
// recordIssues(tools: [sphinxBuild(name: 'Sphinx Doctest', pattern: 'logs/doctest.log', id: 'doctest')])
136-
// }
137-
// }
138-
// }
139-
// stage('Documentation Spell check'){
140-
// steps {
141-
// catchError(buildResult: 'SUCCESS', message: 'Found spelling issues in documentation', stageResult: 'UNSTABLE') {
142-
// sh 'python -m sphinx docs reports/doc_spellcheck -b spelling -d build/docs/doctrees'
143-
// }
144-
// }
145-
// }
129+
stage('Doctest'){
130+
steps {
131+
sh 'uv run coverage run --parallel-mode --source getmarcapi -m sphinx -b doctest -d build/docs/doctrees docs reports/doctest -w logs/doctest.log'
132+
}
133+
post{
134+
always {
135+
recordIssues(tools: [sphinxBuild(name: 'Sphinx Doctest', pattern: 'logs/doctest.log', id: 'doctest')])
136+
}
137+
}
138+
}
139+
stage('Documentation Spell check'){
140+
steps {
141+
catchError(buildResult: 'SUCCESS', message: 'Found spelling issues in documentation', stageResult: 'UNSTABLE') {
142+
sh 'uv run -m sphinx docs reports/doc_spellcheck -b spelling -d build/docs/doctrees'
143+
}
144+
}
145+
}
146146
stage('pyDocStyle'){
147147
steps{
148148
catchError(buildResult: 'SUCCESS', message: 'Did not pass all pyDocStyle tests', stageResult: 'UNSTABLE') {

0 commit comments

Comments
 (0)