Skip to content

Commit f235f1f

Browse files
tazendtazend
committed
Update documentation and do some restructuring (#285)
* update README - include logo - remove testing section (maybe it back separetely in the documentation) - remove workflow-badge (will only fail anyway, add back later when the building process has been updated) * update the documentation * move pyslurm.core.common package to pyslurm.utils * move pyslurm.core.db package to pyslurm.db * rename JobStats to JobStatistics (cherry picked from commit b81d491)
1 parent fe79d64 commit f235f1f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

84 files changed

+803
-474
lines changed

‎README.md‎

Lines changed: 21 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,23 @@
1-
# PySlurm
1+
# <img src="logo.png" alt="PySlurm Logo">
22

3-
[![PySlurm](https://github.com/PySlurm/pyslurm/actions/workflows/pyslurm.yml/badge.svg?branch=main)](https://github.com/PySlurm/pyslurm/actions/workflows/pyslurm.yml)
3+
pyslurm is the Python client library for the [Slurm Workload Manager](https://slurm.schedmd.com)
44

5-
## Overview
6-
7-
PySlurm is the Python client library for the [Slurm](https://slurm.schedmd.com) HPC Scheduler.
8-
9-
## Prerequisites
5+
## Requirements
106

117
* [Slurm](https://slurm.schedmd.com) - Slurm shared library and header files
128
* [Python](https://www.python.org) - >= 3.6
139
* [Cython](https://cython.org) - >= 0.29.30 but < 3.0
1410

15-
This PySlurm branch is for the Slurm Major-Release 22.05
11+
This Version is for Slurm 22.05.x
12+
13+
## Versioning
14+
15+
In pyslurm, the versioning scheme follows the official Slurm versioning. The
16+
first two numbers (`MAJOR.MINOR`) always correspond to Slurms Major-Release,
17+
for example `22.05`.
18+
The last number (`MICRO`) is however not tied in any way to Slurms `MICRO`
19+
version, but is instead PySlurm's internal Patch-Level. For example, any
20+
pyslurm 22.05.X version should work with any Slurm 22.05.X release.
1621

1722
## Installation
1823

@@ -21,14 +26,14 @@ By default, it is searched inside `/usr/include` for the Header files and in
2126
For Slurm installations in different locations, you will need to provide
2227
the corresponding paths to the necessary files.
2328

24-
You can specify these Paths with environment variables (recommended), for example:
29+
You can specify those with environment variables (recommended), for example:
2530

2631
```shell
2732
export SLURM_INCLUDE_DIR=/opt/slurm/22.05/include
2833
export SLURM_LIB_DIR=/opt/slurm/22.05/lib
2934
```
3035

31-
Then you can proceed to install PySlurm, for example by cloning the Repository:
36+
Then you can proceed to install pyslurm, for example by cloning the Repository:
3237

3338
```shell
3439
git clone https://github.com/PySlurm/pyslurm.git && cd pyslurm
@@ -40,105 +45,14 @@ pip install .
4045

4146
Also see `python setup.py --help`
4247

43-
## Release Versioning
44-
45-
PySlurm's versioning scheme follows the official Slurm versioning. The first
46-
two numbers (MAJOR.MINOR) always correspond to Slurms Major-Release, for example
47-
`22.05`. The last number (MICRO) is however not tied in any way to Slurms
48-
MICRO version. For example, any PySlurm 22.05.X version should work with any
49-
Slurm 22.05.X release.
50-
51-
## Documentation
52-
53-
The API documentation is hosted at <https://pyslurm.github.io>.
54-
55-
To build the docs locally, use [Sphinx](http://www.sphinx-doc.org) to generate
56-
the documentation from the reStructuredText based docstrings found in the
57-
pyslurm module once it is built:
58-
59-
```shell
60-
cd doc
61-
make clean
62-
make html
63-
```
64-
65-
## Testing
66-
67-
PySlurm requires an installation of Slurm.
68-
69-
### Using a Test Container
70-
71-
To run tests locally without an existing Slurm cluster, `docker` and
72-
`docker-compose` is required.
73-
74-
Clone the project:
75-
76-
```shell
77-
git clone https://github.com/PySlurm/pyslurm.git
78-
cd pyslurm
79-
```
80-
81-
Start the Slurm container in the background:
82-
83-
```shell
84-
docker-compose up -d
85-
```
86-
87-
The cluster takes a few seconds to start all the required Slurm services. Tail
88-
the logs:
89-
90-
```shell
91-
docker-compose logs -f
92-
```
93-
94-
When the cluster is ready, you will see the following log message:
95-
96-
```text
97-
Cluster is now available
98-
```
99-
100-
Press CTRL+C to stop tailing the logs. Slurm is now running in a container in
101-
detached mode. `docker-compose` also bind mounds the git directory inside the
102-
container at `/pyslurm` so that the container has access to the test cases.
103-
104-
Install test dependencies:
105-
106-
```shell
107-
pipenv sync --dev
108-
```
109-
110-
Execute the tests inside the container:
111-
112-
```shell
113-
pipenv run pytest -sv scripts/run_tests_in_container.py
114-
```
115-
116-
When testing is complete, stop the running Slurm container:
117-
118-
```shell
119-
docker-compose down
120-
```
121-
122-
### Testing on an Existing Slurm Cluster
123-
124-
You may also choose to clone the project and run tests on a node where Slurm is
125-
already compiled and installed:
126-
127-
```shell
128-
git clone https://github.com/PySlurm/pyslurm.git
129-
cd pyslurm
130-
pip install .
131-
./scripts/configure.sh
132-
pipenv sync --dev
133-
pipenv run pytest -sv
134-
```
135-
13648
## Contributors
13749

138-
PySlurm is made by [contributors like
50+
pyslurm is made by [contributors like
13951
you](https://github.com/PySlurm/pyslurm/graphs/contributors).
14052

141-
## Help
53+
## Support
54+
55+
Feel free to ask questions in the [GitHub
56+
Discussions](https://github.com/orgs/PySlurm/discussions)
14257

143-
Ask questions on the [PySlurm Google
144-
Group](https://groups.google.com/forum/#!forum/pyslurm)
58+
Found a bug or you are missing a feature? Feel free to [open an Issue!](https://github.com/PySlurm/pyslurm/issues/new)

‎doc_requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ setuptools
44
mkdocstrings[python]
55
mike
66
mkdocs-material
7+
mkdocs-awesome-pages-plugin

‎docs/index.md‎

Lines changed: 1 addition & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1 @@
1-
---
2-
hide:
3-
- navigation
4-
---
5-
# PySlurm: Slurm Interface to python
6-
7-
This module provides a low-level Python wrapper around the Slurm C-API using Cython.
8-
9-
::: pyslurm.config
10-
handler: python
11-
12-
::: pyslurm.front_end
13-
handler: python
14-
15-
::: pyslurm.hostlist
16-
handler: python
17-
18-
::: pyslurm.job
19-
handler: python
20-
21-
::: pyslurm.jobstep
22-
handler: python
23-
24-
::: pyslurm.node
25-
handler: python
26-
27-
::: pyslurm.partition
28-
handler: python
29-
30-
::: pyslurm.reservation
31-
handler: python
32-
33-
::: pyslurm.slurmdb_events
34-
handler: python
35-
36-
::: pyslurm.slurmdb_reservations
37-
handler: python
38-
39-
::: pyslurm.slurmdb_clusters
40-
handler: python
41-
42-
::: pyslurm.slurmdb_jobs
43-
handler: python
44-
45-
::: pyslurm.statistics
46-
handler: python
47-
48-
::: pyslurm.topology
49-
handler: python
50-
51-
::: pyslurm.trigger
52-
handler: python
1+
--8<-- "README.md"

‎docs/logo.png‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../logo.png

‎docs/reference/.pages‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
title: API Reference
2+
nav:
3+
- ...

‎docs/reference/config.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Config
3+
---
4+
5+
!!! warning
6+
This API is currently being completely reworked, and is subject to be
7+
removed in the future when a replacement is introduced
8+
9+
::: pyslurm.config
10+
handler: python

‎docs/reference/db/.pages‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
title: Database
2+
nav:
3+
- ...

‎docs/reference/db/cluster.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Cluster
3+
---
4+
5+
!!! warning
6+
This API is currently being completely reworked, and is subject to be
7+
removed in the future when a replacement is introduced
8+
9+
::: pyslurm.slurmdb_clusters
10+
handler: python

‎docs/reference/db/connection.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: Connection
3+
---
4+
5+
::: pyslurm.db.Connection
6+
handler: python

‎docs/reference/db/event.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Event
3+
---
4+
5+
!!! warning
6+
This API is currently being completely reworked, and is subject to be
7+
removed in the future when a replacement is introduced
8+
9+
::: pyslurm.slurmdb_events
10+
handler: python

0 commit comments

Comments
 (0)