Skip to content

Commit 92cd4ce

Browse files
AsgmelAsgmel
committed
docs: add docusaurus documentation
1 parent f40007a commit 92cd4ce

39 files changed

+9342
-0
lines changed

‎.github/workflows/docs.yaml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: "📚 Publish Docs"
2+
3+
on:
4+
# Workflow dispatch is used for manual triggers
5+
workflow_dispatch:
6+
# Workflow call is used for called from another workflow
7+
workflow_call:
8+
9+
env:
10+
GITHUB_PAGES_BRANCH: gh-pages
11+
12+
jobs:
13+
publish-docs:
14+
runs-on: ubuntu-latest
15+
16+
steps:
17+
- name: Checkout code
18+
uses: actions/[email protected]
19+
20+
- name: Setup node
21+
uses: actions/setup-node@v3
22+
with:
23+
node-version: 18
24+
cache: yarn
25+
cache-dependency-path: documentation/yarn.lock
26+
27+
- name: Install dependencies and build website
28+
run: |
29+
cd documentation
30+
yarn install --frozen-lockfile
31+
yarn build
32+
33+
- name: Push static files to Github Pages branch
34+
run: |
35+
cd documentation/build
36+
CREATED_FROM_REF=$(git rev-parse --short HEAD)
37+
git init
38+
git config user.name "GitHub Actions Bot"
39+
git config user.email "<>"
40+
git checkout -b $GITHUB_PAGES_BRANCH
41+
git remote add $GITHUB_PAGES_BRANCH https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/equinor/tagreader-python
42+
git add .
43+
git commit -m "Built from commit '$CREATED_FROM_REF'"
44+
git push -f --set-upstream gh-pages gh-pages

‎.github/workflows/on-push-main-branch.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: "✨ On push to main branch"
2+
on:
3+
workflow_dispatch:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
publish-docs:
10+
name: '️‍📚️ Publish Docs'
11+
uses: ./.github/workflows/docs.yaml

‎documentation/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎documentation/.prettierrc.js‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
// default config
2+
module.exports = {
3+
trailingComma: 'es5',
4+
tabWidth: 2,
5+
semi: false,
6+
singleQuote: true,
7+
}

‎documentation/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ yarn
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
### Deployment
28+
29+
Using SSH:
30+
31+
```
32+
$ USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```
38+
$ GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎documentation/babel.config.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎documentation/docs/about/introduction.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
# Introduction
5+
6+
Tagreader is a Python package for reading trend data from the OSIsoft PI and Aspen Infoplus.21 IMS systems. It is
7+
intended to be easy to use, and present as similar interfaces as possible to the backend historians.
8+
9+
While originally developed for Windows, Tagreader can since release 3.0.0 also be used on Linux and Windows platforms.
10+
11+
## Installation
12+
You can install tagreader directly into your project from pypi by using pip
13+
or another package manager.
14+
15+
```shell"
16+
pip install tagreader
17+
```
18+
19+
Please see the [installation](/quickstart) page for more extensive documentation
20+
## Usage
21+
Queries in tagreader can be performed using either REST API (preferred) or ODBC queries. The use of ODBC queries require installation
22+
of proprietary drivers from AspenTech and OSIsoft that are only available for Windows.
23+
24+
For more information on setup and usage of tagreader check out: [Usage](/usage)
25+
26+
For examples on the usage of tagreader check out: [Examples](/examples)
27+
## Contribute
28+
As Tagreader is an open source project, all contributions are welcome. This includes code, bug reports, issues, feature requests, and documentation. The preferred
29+
way of submitting a contribution is to either create an issue on GitHub or to fork the project and make a pull request.
30+
31+
For starting contributing, see the [contribute section](../contribute/how-to-start-contributing.md).

‎documentation/docs/about/quickstart.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
# Quickstart
5+
6+
## Requirements
7+
Python >=3.8 with the following packages:
8+
9+
* pandas >= 1.0.0
10+
* requests
11+
* requests-kerberos
12+
* certifi >= 2023.5.7
13+
* diskcache
14+
* pyodbc (If using ODBC connection)
15+
16+
:::info ODBC Connection
17+
If using ODBC connections, you must also install proprietary drivers for PI ODBC and/or Aspen IP.21 SQLPlus. These
18+
drivers are only available for Microsoft Windows. Pyodbc will therefore not be installed for non-Windows systems.
19+
:::
20+
21+
## installation
22+
To install and/or upgrade:
23+
24+
```shell
25+
pip install --upgrade tagreader
26+
```
27+
If you wish to use ODBC connections to the IMS servers, you will also need to install some proprietary drivers.
28+
See [ODBC drivers](docs/about/setup/odbc-drivers) for more information.
29+
Please note that the web APIs should normally be preferred.
30+
31+
## Usage example
32+
```python
33+
import tagreader
34+
c = tagreader.IMSClient("mysource", "aspenone")
35+
print(c.search("tag*"))
36+
df = c.read_tags(["tag1", "tag2"], "18.06.2020 08:00:00", "18.06.2020 09:00:00", 60)
37+
```
38+
39+
## Jupyter Notebook Quickstart
40+
Jupyter Notebook examples can be found in /examples. In order to run these examples, you need to install the
41+
optional dependencies.
42+
43+
```shell
44+
pip install tagreader[notebooks]
45+
```
46+
47+
The quickstart Jupyter Notebook can be found [here](https://github.com/equinor/tagreader-python/blob/main/examples/quickstart.ipynb)

‎documentation/docs/about/setup/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Setup",
3+
"position": 3,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Examples of tagreader usage."
7+
}
8+
}

‎documentation/docs/about/setup/certificate-management.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Host Certificates
6+
7+
## For Equinor users
8+
9+
***Note**: Since v2.7.0 the procedure described below will be automatically performed on Equinor hosts when importing
10+
the tagreader module. It should therefore no longer be necessary to perform this step manually.*
11+
12+
The Web APIs are queried with the requests package. Requests does not utilize the system certificate store, but instead
13+
relies on the certifi bundle. In order to avoid SSL verification errors, we need to either turn off SSL verification
14+
(optional input argument `verifySSL=False` for relevant function calls) or, strongly preferred, add the certificate to
15+
the certifi bundle. To do this, simply activate the virtual environment where you installed tagreader, and run the
16+
following snippet:
17+
18+
``` python
19+
from tagreader.utils import add_statoil_root_certificate
20+
add_statoil_root_certificate()
21+
```
22+
23+
The output should inform you that the certificate was successfully added. This needs to be repeated whenever certifi is
24+
upgraded in your python virtual environment. It is safe to run more than once: If the function detects that the
25+
certificate has already been added to your current certifi installation, the certificate will not be duplicated.
26+
27+
## For non-Equinor users
28+
29+
If you run info SSL verification errors and prefer to not set `verifySSL=False` , you can try the procedure outlined
30+
[here](https://incognitjoe.github.io/adding-certs-to-requests.html).

0 commit comments

Comments
 (0)