From 8b59f6d5989b160146564247aa6cbfc4410d9bf2 Mon Sep 17 00:00:00 2001 From: Pablo Date: Sun, 7 Aug 2022 22:28:12 +0200 Subject: [PATCH] docs: update docs --- .pre-commit-config.yaml | 2 + CHANGELOG.md | 10 +- CONTRIBUTING.md | 19 ++- README.md | 10 +- docs/examples.md | 333 ++++++++++++++++++++++++++++++++-------- docs/get-started.md | 4 +- docs/index.rst | 2 +- 7 files changed, 303 insertions(+), 77 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8788231..1a9c754 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,3 +1,4 @@ +default_stages: [push] repos: - repo: /~https://github.com/pre-commit/pre-commit-hooks rev: v3.2.0 @@ -24,6 +25,7 @@ repos: rev: v2.28.0 hooks: - id: commitizen + stages: [commit-msg] - repo: /~https://github.com/PyCQA/isort rev: 5.10.1 hooks: diff --git a/CHANGELOG.md b/CHANGELOG.md index 9912d80..0485058 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,10 +4,10 @@ ### Features -* Initial commit (83277e0)[/~https://github.com/pruizlezcano/comicgeeks/commit/83277e07bd17b4bd68684302cf6908759300f142] -* First release (4ef2898)[/~https://github.com/pruizlezcano/comicgeeks/commit/4ef28988ec751ad58187174eeb948539c3bfc6f6] +* Initial commit ([83277e0](/~https://github.com/pruizlezcano/comicgeeks/commit/83277e07bd17b4bd68684302cf6908759300f142)) +* First release ([4ef2898](/~https://github.com/pruizlezcano/comicgeeks/commit/4ef28988ec751ad58187174eeb948539c3bfc6f6)) ### Fixes -* **docs** Error building docs (eb03282)[/~https://github.com/pruizlezcano/comicgeeks/commit/eb03282f15c5684720fed27626cbff23f818455c] -* **docs** More build errors (fe3f7b1)[/~https://github.com/pruizlezcano/comicgeeks/commit/fe3f7b146c8ba5d098a8ed583511e6c833d55a01] -* * **docs** More build errors -_- (e227707)[/~https://github.com/pruizlezcano/comicgeeks/commit/e2277079e7e0d56ef4963788dc42d0f176a85671] +* **docs** Error building docs ([eb03282](/~https://github.com/pruizlezcano/comicgeeks/commit/eb03282f15c5684720fed27626cbff23f818455c)) +* **docs** More build errors ([fe3f7b1](/~https://github.com/pruizlezcano/comicgeeks/commit/fe3f7b146c8ba5d098a8ed583511e6c833d55a01)) +* **docs** More build errors -_- ([e227707](/~https://github.com/pruizlezcano/comicgeeks/commit/e2277079e7e0d56ef4963788dc42d0f176a85671)) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a6ad5c..0f66e24 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -150,11 +150,26 @@ conda activate comicgeeks This should automatically use [flake8]/[black] to check/fix the code style in a way that is compatible with the project. - > Don't forget to add documentation in case your - contribution adds an additional feature and is not just a bugfix. + > Don't forget to add unit tests and documentation in case your contribution adds an additional feature and is not just a bugfix. To commit your changes, please use the [conventional commits] specification. +4. Please check that your changes don't break any unit tests with: + + ``` + tox + ``` + + (after having installed [tox] with `pip install tox` or `pipx`). + + To run all the tests, create a file in the root directory of the project with the name `.devdata.env` and add your [leagueofcomicgeeks.com] ci_session to it: + ``` + CI_SESSION="mycisession" + ``` + + You can also use [tox] to run several other pre-configured tasks in the + repository. Try `tox -av` to see a list of the available checks. + ### Submit your contribution 1. If everything works fine, push your local branch to the remote server with: diff --git a/README.md b/README.md index 835f19a..685230e 100644 --- a/README.md +++ b/README.md @@ -25,19 +25,19 @@ pip install comicgeeks ```python from comicgeeks import Comic_Geeks -scraper = Comic_Geeks("my_ci_session") +client = Comic_Geeks("my_ci_session") # search series -scraper.search_series("daredevil") +client.search_series("daredevil") # get new releases -scraper.new_releases() +client.new_releases() # get info about an issue -scraper.issue_info(3616996) +client.issue_info(3616996) ``` -For more info check the documentation in [http...](http...) +For more info check the documentation in [https://comicgeeks.readthedocs.io](https://comicgeeks.readthedocs.io) ## Contributing Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. diff --git a/docs/examples.md b/docs/examples.md index 4d1c2ad..9659a55 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,6 +1,8 @@ # Examples -## Search series +## Search + +### Search series ```python from comicgeeks import Comic_Geeks @@ -10,7 +12,36 @@ series = comic_geeks.search_series("Daredevil") ``` ```{admonition} Return +```{eval-rst} + .. code-block:: none + + [ + , + , + , + , + , + , + , + , + , + , + 94 more... + ] + +``` + +### Search creator + +```python +from comicgeeks import Comic_Geeks +client = Comic_Geeks() +creators = client.search_creator("Chip") +``` + +```{admonition} Return +```{eval-rst} .. code-block:: none [ @@ -28,17 +59,44 @@ series = comic_geeks.search_series("Daredevil") ] ``` -## Get new releases - +### Search character ```python from comicgeeks import Comic_Geeks -comic_geeks = Comic_Geeks() -series = comic_geeks.new_releases() +client = Comic_Geeks() +characters = client.search_character("Spider-man") ``` ```{admonition} Return +```{eval-rst} + .. code-block:: none + [ + , + , + , + , + , + , + , + , + , + , + 40 more... + ] +``` + +### Get new releases + +```python +from comicgeeks import Comic_Geeks + +client = Comic_Geeks() +issues = client.new_releases() +``` + +```{admonition} Return +```{eval-rst} .. code-block:: none [ @@ -56,24 +114,26 @@ series = comic_geeks.new_releases() ] ``` -## Get individual series +## Get by id + +### Get series ```python from comicgeeks import Comic_Geeks -comic_geeks = Comic_Geeks() -series = comic_geeks.series_info(150065) +client = Comic_Geeks() +series = client.series_info(150065) ``` ```{admonition} Return - +```{eval-rst} .. code-block:: json { - "series_id": "150065", + "series_id": 150065, "name": "Beta Ray Bill", "publisher": "Marvel Comics", - "description": "

Beta Ray Bill is tired of playing second fiddle to Thor – and with Beta Ray’s famous hammer Stormbreaker recently destroyed at the new All-Father’s hands, tensions are higher than ever. The mighty Korbinite must strike out in search of a new weapon… and a new destiny. Assuming he can first defeat a Knullified Fin Fang Foom! Joined by colorist Mike Spicer, Daniel Warren Johnson will take Beta Ray Bill on a journey beyond the shadow of a god!

", + "description": "Beta Ray Bill is tired of playing second fiddle to Thor – and with Beta Ray’s famous hammer Stormbreaker recently destroyed at the new All-Father’s hands, tensions are higher than ever. The mighty Korbinite must strike out in search of a new weapon… and a new destiny. Assuming he can first defeat a Knullified Fin Fang Foom! Joined by colorist Mike Spicer, Daniel Warren Johnson will take Beta Ray Bill on a journey beyond the shadow of a god!", "start_year": 2021, "end_year": 2021, "issues": [ @@ -85,87 +145,234 @@ series = comic_geeks.series_info(150065) ], "issue_count": 5, "url": "/comics/series/150065/beta-ray-bill", - "cover": "https://s3.amazonaws.com/comicgeeks/series/150065.jpg?1619183332" + "cover": "https://s3.amazonaws.com/comicgeeks/series/150065.jpg?1619183332", + "user": { // Only valid if ci_session is provided + "pull": "None", + "owned": "None", + "read": "None" + } } ``` -## Get individual issue +### Get issue ```python from comicgeeks import Comic_Geeks -comic_geeks = Comic_Geeks() -series = comic_geeks.issue_info(3616996) +client = Comic_Geeks() +issue = client.issue_info(3616996) ``` ```{admonition} Return - +```{eval-rst} .. code-block:: json { - "issue_id": "3616996", + "issue_id": 3616996, "character_credits": [ - "", - "", - "", - "", - "", - "", - "", - "", - "", - "", - "", - "" + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "" ], "cover": { - "name": "Daredevil #8", - "image": "https://s3.amazonaws.com/comicgeeks/comics/covers/large-3616996.jpg?1629150053" + "name": "Daredevil #8", + "image": "https://s3.amazonaws.com/comicgeeks/comics/covers/large-3616996.jpg?1629150053" + }, + "community": { + "pull": "Unknown", + "collect": 1177, + "readlist": 1350, + "wishlist": 202, + "rating": 96 }, - "community": {"pull": "43", "collect": "1,159", "readlist": "1,289", "wishlist": "195", "rating": "96"}, "description": "NO DEVILS, ONLY GOD, PART 3\xa0With Daredevil still missing, his shadow looms large over Hell’s Kitchen…and ordinary citizens are starting to feel his absence. Detective Cole North may think he’s stopped Daredevil, but there are bigger problems coming his way!\xa0LEGACY #620", "details": { - "format": "comic", - "page_count": "28 pages", - "upc": "75960609142300811", - "distributor_sku": "may190864" + "format": "comic", + "page_count": "28 pages", + "upc": "75960609142300811", + "distributor_sku": "may190864" }, "name": "No Devils, Only God, Part 3", "number": "8", "person_credits": [ - {"role": "writer, cover artist", "Creator": ""}, - {"role": "penciller", "Creator": ""}, - {"role": "inker", "Creator": ""} - {"role": "colorist", "Creator": ""}, - {"role": "letterer", "Creator": ""}, - {"role": "variant cover artist", "Creator": ""}, - {"role": "variant cover artist", "Creator": ""}, - {"role": "variant cover artist", "Creator": ""}, - {"role": "assistant editor", "Creator": ""}, - {"role": "editor", "Creator": ""}, - {"role": "executive editor", "Creator": ""}, - {"role": "editor-in-chief", "Creator": ""} + { + "role": "writer, cover artist", + "Creator": "" + }, + { + "role": "penciller", + "Creator": "" + }, + { + "role": "inker", + "Creator": "" + }, + { + "role": "colorist", + "Creator": "" + }, + { + "role": "letterer", + "Creator": "" + }, + { + "role": "variant cover artist", + "Creator": "" + }, + { + "role": "variant cover artist", + "Creator": "" + }, + { + "role": "variant cover artist", + "Creator": "" + }, + { + "role": "assistant editor", + "Creator": "" + }, + { + "role": "editor", + "Creator": "" + }, + { + "role": "executive editor", + "Creator": "" + }, + { + "role": "editor-in-chief", + "Creator": "" + } ], - "price": "$3.99", + "price": 3.99, "publisher": "Marvel Comics", "pagination": { - "prev": "", - "series": "", - "next": "" + "prev": "", + "series": "", + "next": "" }, "store_date": 1563314400, "url": "/comic/3616996/daredevil-8", "variant_covers": [ - { - "name": "Daredevil #8 2nd Printing", - "url": "/comic/3616996/daredevil-8?variant=8785071", - "image": "https://s3.amazonaws.com/comicgeeks/comics/covers/medium-8785071.jpg?1610895121" - }, - { - "name": "Daredevil #8 Lee Garbett Carnage-ized Variant", - "url": "/comic/3616996/daredevil-8?variant=5800290", - "image": "https://s3.amazonaws.com/comicgeeks/comics/covers/medium-5800290.jpg?1607293889" - } - ] + { + "name": "Daredevil #8 2nd Printing", + "url": "/comic/3616996/daredevil-8?variant=8785071", + "image": "https://s3.amazonaws.com/comicgeeks/comics/covers/medium-8785071.jpg?1610895121" + }, + { + "name": "Daredevil #8 Lee Garbett Carnage-ized Variant", + "url": "/comic/3616996/daredevil-8?variant=5800290", + "image": "https://s3.amazonaws.com/comicgeeks/comics/covers/medium-5800290.jpg?1607293889" + } + ], + "user": { // Only valid if ci_session is provided + "pull": "None", + "collect": "None", + "readlist": "None", + "wishlist": "None", + "rating": "None" + } + } +``` + +### Get creator + +```python +from comicgeeks import Comic_Geeks + +client = Comic_Geeks() +creator = client.creator_info(6209) +``` + +```{admonition} Return +```{eval-rst} + .. code-block:: json + + { + "characters": [ + "", + "", + "", + "", + "", + "and many more..." + ], + "series": [ + "", + "", + "", + "", + "", + "and many more..." + ], + "creator_id": 6209, + "description": "Steve Murray (better known under the pen name of Chip Zdarsky) is a Canadian comic book creator most known for his work with Matt Fraction in Sex Criminals\xa0as the artist and his books at Marvel such as Daredevil, The Spectacular Spider-Man and Howard the Duck.", + "image": "https://s3.amazonaws.com/comicgeeks/people/avatars/6209.jpg?t=1604083961", "name": "Chip Zdarsky", + "url": "/people/6209/chip-zdarsky", + "read": "None", // Only valid if ci_session is provided + "owned": "None", // Only valid if ci_session is provided + "issue_count": 378 + } +``` + +### Get character +```python +from comicgeeks import Comic_Geeks + +client = Comic_Geeks() +character = client.creator_info(6209) +``` + +```{admonition} Return +```{eval-rst} + .. code-block:: json + + { + "character_id": 11699, + "image": "https://s3.amazonaws.com/comicgeeks/characters/avatars/11699.jpg?t=1608688306", + "creators": [ + "", + "" + ], + "description": "The lethal scarlet assassin. Elektra is Daredevil's most fearsome enemy, as well as his former lover, and most renowned assassin in the world.", + "information": [ + { + "key": "First Appearance", + "value": "Daredevil #25" + } + ], + "also_known_as": [], + "series": [ + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "" + ], + "universe": "Earth-616", + "publisher": "Marvel Comics", + "name": "Daredevil", + "real_name": "Elektra Natchios", + "url": "/character/11699/daredevil", + "read": "None", // Only valid if ci_session is provided + "owned": "None", // Only valid if ci_session is provided + "issue_count": 37 } ``` diff --git a/docs/get-started.md b/docs/get-started.md index 69d9065..1cc86f3 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -22,7 +22,7 @@ To do that, follow this steps: ```python from comicgeeks import Comic_Geeks -scraper = Comic_Geeks("my_ci_session") +scraper = Comic_Geeks("mycisession") # search series scraper.search_series("daredevil") @@ -33,3 +33,5 @@ scraper.new_releases() # get info about an issue scraper.issue_info(3616996) ``` + +Check the [examples](/examples) tab for more use cases. diff --git a/docs/index.rst b/docs/index.rst index d765906..26add3d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,7 +16,7 @@ comicgeeks .. toctree:: :caption: comicgeeks - :maxdepth: 2 + :maxdepth: 3 :hidden: get-started