From d64f9b5401849573f0656ddd707460720cd53d1d Mon Sep 17 00:00:00 2001 From: Harpo Harbert Date: Thu, 21 Mar 2024 11:16:42 -0700 Subject: [PATCH] Adds MIT license, cleans docs --- LICENSE | 7 +++ docs/{interpreter.ipynb => example.ipynb} | 16 ++++--- docs/index.md | 10 +++-- docs/install.md | 53 +++++++++++++++++++---- 4 files changed, 67 insertions(+), 19 deletions(-) create mode 100644 LICENSE rename docs/{interpreter.ipynb => example.ipynb} (91%) diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2ada842 --- /dev/null +++ b/LICENSE @@ -0,0 +1,7 @@ +Copyright 2023 GBH + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/docs/interpreter.ipynb b/docs/example.ipynb similarity index 91% rename from docs/interpreter.ipynb rename to docs/example.ipynb index 427c62b..310b29f 100644 --- a/docs/interpreter.ipynb +++ b/docs/example.ipynb @@ -5,7 +5,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Interpreter\n", + "# Example\n", + "\n", + "This example demonstrates how to use the `ci` command line tool to interact with the SonyCi API.\n", "\n", "## Token\n", "\n", @@ -30,7 +32,7 @@ "source": [ "import logging\n", "\n", - "logging.getLogger('requests.packages.urllib3').setLevel(logging.DEBUG)\n" + "logging.getLogger(\"requests.packages.urllib3\").setLevel(logging.DEBUG)" ] }, { @@ -75,7 +77,7 @@ " client_id=client_id,\n", " client_secret=client_secret,\n", " workspace_id=workspace_id,\n", - ")\n" + ")" ] }, { @@ -127,7 +129,7 @@ "from sonyci.sonyci import SonyCi\n", "\n", "\n", - "ci = SonyCi(t=token)\n" + "ci = SonyCi(t=token)" ] }, { @@ -155,8 +157,8 @@ "metadata": {}, "outputs": [], "source": [ - "ci = SonyCi.load_from_toml('../ci.toml')\n", - "ci('workspaces')\n" + "ci = SonyCi.load_from_toml(\"../ci.toml\")\n", + "ci(\"workspaces\")" ] } ], @@ -176,7 +178,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.3" + "version": "3.12.1" }, "orig_nbformat": 4 }, diff --git a/docs/index.md b/docs/index.md index 05cf8e7..3b365d6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,14 +1,18 @@ # SonyCi -A [SonyCi](https://developers.cimediacloud.com/#workspaces-list-workspaces-contents-get) API client for Python +A Python client for [SonyCi API](https://developers.cimediacloud.com/) ## Install -Install instructions can be found on the [install page](install) +Install instructions can be found on the [install page](install.md) ## Reference -Further details can be found in the [reference section](reference) +Further details can be found in the [reference section](reference.md) + +## License + +[MIT License](https://github.com/WGBH-MLA/sonyci/blob/main/LICENSE) ## Credits diff --git a/docs/install.md b/docs/install.md index e6e1cbd..75ac434 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,5 +1,17 @@ # Install +This guide will walk you through the installation process for the `sonyci` package. It can be installed with `pip` or `pdm` + +## (Option 1) Install with pip + +```shell +pip install sonyci +``` + +## (Option 2) Install with pdm + +[PDM](https://pdm.fming.dev/) is used as the packaging manager. It can be installed with `pip install pdm`. + ### Clone the repository:: ```shell @@ -7,9 +19,7 @@ git clone https://github.com/WGBH-MLA/sonyci.git cd sonyci ``` -### Install with PDM - -[PDM](https://pdm.fming.dev/) is used as the packaging manager. It can be installed with `pip install pdm`. +### Install Install the project with development dependencies: @@ -52,7 +62,7 @@ $(pdm venv activate) deactivate ``` -### Login +## Login The first time you run the application, you will need to get an access token. You can do this with the `login` command: @@ -60,7 +70,7 @@ The first time you run the application, you will need to get an access token. Yo ci login ``` -#### Credentials +### Credentials You will need to provide your `username` and `password`, as well as your `client_id` and `client_secret`. These can be provided as command line options, or (recommended) as `ENVIRONMENT_VARIABLES`: @@ -74,21 +84,31 @@ export CI_CLIENT_SECRET= export CI_WORKSPACE_ID= ``` +!!! abstract inline end "Dot notation" + + Alternate notation for `source` (may not be available in your terminal): + + ```shell + . .cred + ``` + Activate the variables: ```shell source .cred ``` -!!! abstract "Dot notation" +!!! abstract "Check ennvironment variables" - Alternate notation (may not be available in your terminal): + To check your environment variables are stored, run: ```shell - . .cred + echo $CI_USERNAME ``` -Now you can login and get an access token: + If your username does not appear, you may need to run the `source` command again. + +Otherwise, you can now login and get an access token: ```shell ci login @@ -105,3 +125,18 @@ ci -h ``` See the [CLI reference](../reference/cli) for more details. + +## Development + +Additional development scripts are available in the `pyproject.toml` file. You can run them with `pdm `. For example, to run the tests: + +```shell +pdm test +``` + +### Available scripts + +- `test`: Run the tests +- `lint`: Run the linter, autofix fixable issues +- `format`: Format the code +- `docs`: Build the documentation