From 95afc10ee485369258813bba2d335131ee35b0f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Kucmus?= Date: Mon, 8 Jan 2024 23:27:11 +0100 Subject: [PATCH 1/4] add index page for docs --- README.md | 16 ++-- docs/assets/marina_logo.svg | 105 +++++++++++++++++++++++++ docs/assets/marina_logo_black.svg | 25 ++++++ docs/assets/marina_logo_white.svg | 26 ++++++ docs/assets/mirumee.png | Bin 0 -> 6386 bytes docs/css/extra.css | 21 +++++ docs/index.md | 27 ++++++- docs/overrides/partials/copyright.html | 19 +++++ mkdocs.yml | 4 + 9 files changed, 237 insertions(+), 6 deletions(-) create mode 100644 docs/assets/marina_logo.svg create mode 100644 docs/assets/marina_logo_black.svg create mode 100644 docs/assets/marina_logo_white.svg create mode 100644 docs/assets/mirumee.png create mode 100644 docs/overrides/partials/copyright.html diff --git a/README.md b/README.md index 508b989..b27cd56 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,9 @@ Documentation, contribution rules, process and the code itself (this includes th ## Installation -Install [Hatch](https://hatch.pypa.io/latest/install/#pipx). +``` +pip install saleor-sdk-python +``` ## Tooling @@ -26,7 +28,11 @@ saleor-sdk tools decode-id VXNlcjoyMg== saleor-sdk tools encode-id User 22 ``` -## Documentation +## Development + +Install [Hatch](https://hatch.pypa.io/latest/install/#pipx). + +### Documentation ``` hatch run docs:serve @@ -34,20 +40,20 @@ hatch run docs:serve and navigate to http://127.0.0.1:8000 -## Tests +### Tests ``` hatch run test ``` -## Build and deploy +### Build and deploy ``` hatch build -c hatch publish ``` -## Code style +### Code style ``` hatch run lint:fmt diff --git a/docs/assets/marina_logo.svg b/docs/assets/marina_logo.svg new file mode 100644 index 0000000..272cb03 --- /dev/null +++ b/docs/assets/marina_logo.svg @@ -0,0 +1,105 @@ + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/marina_logo_black.svg b/docs/assets/marina_logo_black.svg new file mode 100644 index 0000000..209177f --- /dev/null +++ b/docs/assets/marina_logo_black.svg @@ -0,0 +1,25 @@ + + + + + + + + + + diff --git a/docs/assets/marina_logo_white.svg b/docs/assets/marina_logo_white.svg new file mode 100644 index 0000000..c0f2498 --- /dev/null +++ b/docs/assets/marina_logo_white.svg @@ -0,0 +1,26 @@ + + + + + + + + + + diff --git a/docs/assets/mirumee.png b/docs/assets/mirumee.png new file mode 100644 index 0000000000000000000000000000000000000000..d3375f80e95203278068bfe09c0671599ccd9de9 GIT binary patch literal 6386 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 + {% if config.copyright %} +
+ {{ config.copyright }} +
+ {% endif %} + {% if not config.extra.generator == false %} + Made with + + Material for MkDocs + + {% endif %} +
+ Saleor SDK Python is crafted with love by +
+ diff --git a/mkdocs.yml b/mkdocs.yml index 72f05a9..315dd57 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,9 +1,13 @@ site_name: Saleor SDK Python repo_url: https://github.com/mirumee/saleor-sdk-python edit_uri: edit/main/docs/ +copyright: Copyright © 2024 - Mirumee Software theme: + logo: /assets/marina_logo_white.svg + favicon: /assets/marina_logo.svg name: material + custom_dir: docs/overrides palette: # Palette toggle for light mode - media: "(prefers-color-scheme: light)" From e9663a190c2cd6ba7a4ae6a1ce8dc4b3cf1c2640 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Kucmus?= Date: Tue, 9 Jan 2024 16:53:03 +0100 Subject: [PATCH 2/4] improve documentation --- README.md | 23 +++++++++++++++++------ docs/index.md | 4 ++-- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index b27cd56..594edf1 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,14 @@ saleor-sdk tools encode-id User 22 ## Development +To contribute to this repository you will need Hatch to setup a local development environment. + Install [Hatch](https://hatch.pypa.io/latest/install/#pipx). ### Documentation +You can deploy a local documentation service, it reloads changes and allow for a live preview of how the documentation will look like after publication: + ``` hatch run docs:serve ``` @@ -42,20 +46,27 @@ and navigate to http://127.0.0.1:8000 ### Tests +With the following command you can run tests: + ``` hatch run test ``` -### Build and deploy +### Code style + +This library follows a specific style guide, to achieve the proper format and lint the code the following commands should be used: ``` -hatch build -c -hatch publish +hatch run lint:fmt +hatch run lint:all ``` -### Code style + +### Build and deploy + +This is done by a CI/CD workflow upon the creation of a release but in case of the need for a manual publication of the packager to PyPI you need to build the package archive and publish it. ``` -hatch run lint:fmt -hatch run lint:all +hatch build -c +hatch publish ``` diff --git a/docs/index.md b/docs/index.md index ede1146..09cb3c4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,8 +18,8 @@ pip install saleor-sdk-python ## Key features -- CLI with tooling that helps to decode Saleor IDs -- Crypto module helping with Saleor authentication, both JWT verification and webhook signature verification +- CLI with tooling that helps to decode and encode Saleor IDs - this is useful when a entity type or ID needs to be recognized from a GraphQL ID +- Crypto module helping with Saleor authentication, both JWT verification and webhook signature verification - provides a way to manage Saleor issued signatures - Marina module - more on that in a later time... ## Best served with From 55216132592b00a9a22b4608a06e8d5a902719ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Kucmus?= Date: Tue, 9 Jan 2024 22:08:50 +0100 Subject: [PATCH 3/4] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rafał Pitoń --- README.md | 6 +++--- docs/index.md | 4 +++- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 594edf1..a802573 100644 --- a/README.md +++ b/README.md @@ -46,15 +46,15 @@ and navigate to http://127.0.0.1:8000 ### Tests -With the following command you can run tests: +To run tests suite use the following command: ``` hatch run test ``` -### Code style +### Code style and linters -This library follows a specific style guide, to achieve the proper format and lint the code the following commands should be used: +Use the following commands to format the code and lint it for issues: ``` hatch run lint:fmt diff --git a/docs/index.md b/docs/index.md index 09cb3c4..4eda43a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,7 +18,9 @@ pip install saleor-sdk-python ## Key features -- CLI with tooling that helps to decode and encode Saleor IDs - this is useful when a entity type or ID needs to be recognized from a GraphQL ID +- CLI tools automating common development tasks: testing, linting and publication. +- CLI utility for deserializing Saleor's GraphQL IDs values to reveal type names and their database IDs - helpful in debugging and local development. +- - Crypto module helping with Saleor authentication, both JWT verification and webhook signature verification - provides a way to manage Saleor issued signatures - Marina module - more on that in a later time... From 4a378e4976ff535b7a4a985424cd39e72621c74e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Jagodzi=C5=84ski?= Date: Mon, 29 Jan 2024 09:26:03 +0100 Subject: [PATCH 4/4] Apply changes from code review --- .gitignore | 2 +- README.md | 10 ++++++++-- docs/index.md | 14 +++++++++----- 3 files changed, 18 insertions(+), 8 deletions(-) diff --git a/.gitignore b/.gitignore index 437035f..734267e 100644 --- a/.gitignore +++ b/.gitignore @@ -157,7 +157,7 @@ cython_debug/ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ +.idea/ .vscode .ruff_cache .python-version diff --git a/README.md b/README.md index a802573..009219e 100644 --- a/README.md +++ b/README.md @@ -36,12 +36,16 @@ Install [Hatch](https://hatch.pypa.io/latest/install/#pipx). ### Documentation -You can deploy a local documentation service, it reloads changes and allow for a live preview of how the documentation will look like after publication: +1. Run the below command to start a dev server with the documentation site: ``` hatch run docs:serve ``` +Dev server provides a live reload on changes and lets you preview the site after it's published + + + and navigate to http://127.0.0.1:8000 ### Tests @@ -64,7 +68,9 @@ hatch run lint:all ### Build and deploy -This is done by a CI/CD workflow upon the creation of a release but in case of the need for a manual publication of the packager to PyPI you need to build the package archive and publish it. +To publish a new version to PyPI, update it's version number in the `pyproject/toml` file and create new github release. + +In case whe you need to make a new release without GitHub workflow, use following `hatch` commands: ``` hatch build -c diff --git a/docs/index.md b/docs/index.md index 4eda43a..fc854be 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,14 +1,18 @@ # Introduction -Saleor SDK Python is a Python library which purpose is to contain code that is repeated in different Saleor applications. +Saleor SDK Python is a Python library that implements tools and solutions useful in Saleor application development, including: -You should read [Saleor's Documentation](https://docs.saleor.io/docs/3.x/developer/extending/overview) on the topic to get a grasp on the concepts of the "app framework" Saleor comes with. +- the `saleor_sdk.crypto` package for working with Saleor's auth. -This SDK is agnostic of any framework, which makes it possible to use in all sorts of web (or otherwise) frameworks and even scripts. +Before starting, you should familiarize yourself with Saleor's [Extending Saleor](https://docs.saleor.io/docs/3.x/developer/extending/overview) documentation +and learn basic concepts like apps, webhooks and events. -## What about Python App Framework? -The old [saleor-app-framework-python](https://github.com/mirumee/saleor-app-framework-python) was very opinionated on how an application should be crated. It required FastAPI and in a specific version of it. +This SDK is framework agnostic. It can be used with any Python web framework, or without framework as part of a script. + +## What about the Python App Framework? + +The [saleor-app-framework-python](https://github.com/mirumee/saleor-app-framework-python) has been deprecated and is no longer maintained. ## Installation