docs: improving documentation generation

201st-Luka · Sep 11, 2023 · 77f7cda · 77f7cda
1 parent 94e948a
commit 77f7cda
Show file tree

Hide file tree

Showing 90 changed files with 141 additions and 48 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,24 @@
+name: doc generation
+on:
+ push:
+ branches:
+ - master
+permissions:
+ contents: write
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ - uses: actions/setup-python@v4
+ with:
+ python-version: 3.x
+ - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+ - uses: actions/cache@v3
+ with:
+ key: mkdocs-material-${{ env.cache_id }}
+ path: .cache
+ restore-keys: |
+ mkdocs-material-
+ - run: pip install -r requirements-docs.txt
+ - run: mkdocs gh-deploy --force
diff --git a/docs/doc_autogen.py → doc_gen.py b/docs/doc_autogen.py → doc_gen.py
@@ -16,25 +16,26 @@ def create_markdown_structure(package_path, output_path):
  output_path (str): The path where the directory structure and markdown files will be generated.
  """
  for dirpath, dirnames, filenames in os.walk(package_path):
- # Create corresponding directory structure in the output path
  relative_dir = os.path.relpath(dirpath, package_path)
  output_dir = os.path.join(output_path, relative_dir)
  os.makedirs(output_dir, exist_ok=True)
 
  for filename in filenames:
  if filename.endswith('.py') and filename != "__init__.py":
  module_name = os.path.splitext(filename)[0]
- import_path = "pyclasher." + '/'.join(
- os.path.split(
- os.path.join(relative_dir, module_name))
- ).replace('.', '').replace('/', '.')
- print(import_path)
+ import_path = (
+ "pyclasher." +
+ os.path.join(relative_dir if relative_dir != '.'
+ else '',
+ module_name)
+ ).replace('/', '.')
  markdown_content = f"::: {import_path}\n"
 
- # Create a markdown file with the import path as content
  markdown_file_path = os.path.join(output_dir,
  f"{module_name}.md")
+
  with open(markdown_file_path, 'w') as markdown_file:
+ print(f"Creating docs for {import_path}")
  markdown_file.write(markdown_content)
 
 
@@ -43,13 +44,11 @@ def create_markdown_structure(package_path, output_path):
 
  doc_dir = os.path.join(project_dir, "docs")
 
- api_ref_dir = os.path.join(doc_dir, "API Reference")
+ api_ref_dir = os.path.join(doc_dir, "docs/API Reference")
  pyclasher_dir = os.path.join(project_dir, "pyclasher")
 
  shutil.rmtree(api_ref_dir)
 
  os.mkdir(api_ref_dir)
 
  create_markdown_structure(pyclasher_dir, api_ref_dir)
-
-
diff --git a/docs/API Reference/.pages b/docs/API Reference/.pages
diff --git a/docs/API Reference/API/Bulk requests/abc.md b/docs/API Reference/API/Bulk requests/abc.md
diff --git a/docs/API Reference/API/Bulk requests/bulk_player.md b/docs/API Reference/API/Bulk requests/bulk_player.md
diff --git a/docs/API Reference/API/Models/login/login_models.md b/docs/API Reference/API/Models/login/login_models.md
diff --git a/docs/API Reference/API/Models/misc/api.md b/docs/API Reference/API/Models/misc/api.md
diff --git a/docs/API Reference/API/Models/misc/posts.md b/docs/API Reference/API/Models/misc/posts.md
diff --git a/docs/API Reference/API/Models/misc/responses.md b/docs/API Reference/API/Models/misc/responses.md
diff --git a/docs/API Reference/API/Models/misc/war_status.md b/docs/API Reference/API/Models/misc/war_status.md
diff --git a/docs/API Reference/Client/client.md b/docs/API Reference/Client/client.md
diff --git a/docs/API Reference/Client/request_consumer.md b/docs/API Reference/Client/request_consumer.md
diff --git a/docs/API Reference/Client/request_queue.md b/docs/API Reference/Client/request_queue.md
diff --git a/docs/API Reference/Utils/exectimer.md b/docs/API Reference/Utils/exectimer.md
diff --git a/docs/API Reference/Utils/functions.md b/docs/API Reference/Utils/functions.md
diff --git a/docs/API Reference/Utils/request_methods.md b/docs/API Reference/Utils/request_methods.md
diff --git a/docs/API Reference/api/bulk_requests/abc.md b/docs/API Reference/api/bulk_requests/abc.md
@@ -0,0 +1 @@
+::: pyclasher.api.bulk_requests.abc
diff --git a/docs/API Reference/api/bulk_requests/b_player.md b/docs/API Reference/api/bulk_requests/b_player.md
@@ -0,0 +1 @@
+::: pyclasher.api.bulk_requests.b_player
diff --git a/docs/API Reference/api/models/abc.md b/docs/API Reference/api/models/abc.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.abc
diff --git a/docs/API Reference/api/models/base_models.md b/docs/API Reference/api/models/base_models.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.base_models
diff --git a/docs/API Reference/api/models/clan.md b/docs/API Reference/api/models/clan.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan
diff --git a/docs/API Reference/api/models/clan_builder_base_ranking_list.md b/docs/API Reference/api/models/clan_builder_base_ranking_list.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan_builder_base_ranking_list
diff --git a/docs/API Reference/api/models/clan_capital_raid_seasons.md b/docs/API Reference/api/models/clan_capital_raid_seasons.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan_capital_raid_seasons
diff --git a/docs/API Reference/api/models/clan_capital_ranking_list.md b/docs/API Reference/api/models/clan_capital_ranking_list.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan_capital_ranking_list
diff --git a/docs/API Reference/api/models/clan_list.md b/docs/API Reference/api/models/clan_list.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan_list
diff --git a/docs/API Reference/api/models/clan_member.md b/docs/API Reference/api/models/clan_member.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan_member
diff --git a/docs/API Reference/api/models/clan_member_list.md b/docs/API Reference/api/models/clan_member_list.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan_member_list
diff --git a/docs/API Reference/api/models/clan_ranking_list.md b/docs/API Reference/api/models/clan_ranking_list.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan_ranking_list
diff --git a/docs/API Reference/api/models/clan_war.md b/docs/API Reference/api/models/clan_war.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan_war
diff --git a/docs/API Reference/api/models/clan_war_league_group.md b/docs/API Reference/api/models/clan_war_league_group.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan_war_league_group
diff --git a/docs/API Reference/api/models/clan_war_log.md b/docs/API Reference/api/models/clan_war_log.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.clan_war_log
diff --git a/docs/API Reference/api/models/enums.md b/docs/API Reference/api/models/enums.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.enums
diff --git a/docs/API Reference/api/models/gold_pass_season.md b/docs/API Reference/api/models/gold_pass_season.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.gold_pass_season
diff --git a/docs/API Reference/api/models/labels.md b/docs/API Reference/api/models/labels.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.labels
diff --git a/docs/API Reference/api/models/language.md b/docs/API Reference/api/models/language.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.language
diff --git a/docs/API Reference/api/models/leagues.md b/docs/API Reference/api/models/leagues.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.leagues
diff --git a/docs/API Reference/api/models/location.md b/docs/API Reference/api/models/location.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.location
diff --git a/docs/API Reference/api/models/login/login_models.md b/docs/API Reference/api/models/login/login_models.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.login.login_models
diff --git a/docs/API Reference/api/models/misc/api.md b/docs/API Reference/api/models/misc/api.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.misc.api
diff --git a/docs/API Reference/api/models/misc/posts.md b/docs/API Reference/api/models/misc/posts.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.misc.posts
diff --git a/docs/API Reference/api/models/misc/responses.md b/docs/API Reference/api/models/misc/responses.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.misc.responses
diff --git a/docs/API Reference/api/models/misc/war_status.md b/docs/API Reference/api/models/misc/war_status.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.misc.war_status
diff --git a/docs/API Reference/api/models/player.md b/docs/API Reference/api/models/player.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.player
diff --git a/docs/API Reference/api/models/player_builder_base_ranking_list.md b/docs/API Reference/api/models/player_builder_base_ranking_list.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.player_builder_base_ranking_list
diff --git a/docs/API Reference/api/models/player_house.md b/docs/API Reference/api/models/player_house.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.player_house
diff --git a/docs/API Reference/api/models/player_ranking_clan.md b/docs/API Reference/api/models/player_ranking_clan.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.player_ranking_clan
diff --git a/docs/API Reference/api/models/player_ranking_list.md b/docs/API Reference/api/models/player_ranking_list.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.player_ranking_list
diff --git a/docs/API Reference/api/models/season.md b/docs/API Reference/api/models/season.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.season
diff --git a/docs/API Reference/api/models/war_clan.md b/docs/API Reference/api/models/war_clan.md
@@ -0,0 +1 @@
+::: pyclasher.api.models.war_clan
diff --git a/docs/API Reference/api/requests/abc.md b/docs/API Reference/api/requests/abc.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.abc
diff --git a/docs/API Reference/api/requests/builder_base_league.md b/docs/API Reference/api/requests/builder_base_league.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.builder_base_league
diff --git a/docs/API Reference/api/requests/builder_base_leagues.md b/docs/API Reference/api/requests/builder_base_leagues.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.builder_base_leagues
diff --git a/docs/API Reference/api/requests/capital_league.md b/docs/API Reference/api/requests/capital_league.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.capital_league
diff --git a/docs/API Reference/api/requests/capital_league_seasons.md b/docs/API Reference/api/requests/capital_league_seasons.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.capital_league_seasons
diff --git a/docs/API Reference/api/requests/capital_rankings.md b/docs/API Reference/api/requests/capital_rankings.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.capital_rankings
diff --git a/docs/API Reference/api/requests/clan.md b/docs/API Reference/api/requests/clan.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan
diff --git a/docs/API Reference/api/requests/clan_builder_base_rankings.md b/docs/API Reference/api/requests/clan_builder_base_rankings.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan_builder_base_rankings
diff --git a/docs/API Reference/api/requests/clan_capital_raid_seasons.md b/docs/API Reference/api/requests/clan_capital_raid_seasons.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan_capital_raid_seasons
diff --git a/docs/API Reference/api/requests/clan_current_war.md b/docs/API Reference/api/requests/clan_current_war.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan_current_war
diff --git a/docs/API Reference/api/requests/clan_currentwar_leaguegroup.md b/docs/API Reference/api/requests/clan_currentwar_leaguegroup.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan_currentwar_leaguegroup
diff --git a/docs/API Reference/api/requests/clan_labels.md b/docs/API Reference/api/requests/clan_labels.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan_labels
diff --git a/docs/API Reference/api/requests/clan_members.md b/docs/API Reference/api/requests/clan_members.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan_members
diff --git a/docs/API Reference/api/requests/clan_rankings.md b/docs/API Reference/api/requests/clan_rankings.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan_rankings
diff --git a/docs/API Reference/api/requests/clan_search.md b/docs/API Reference/api/requests/clan_search.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan_search
diff --git a/docs/API Reference/api/requests/clan_war_log.md b/docs/API Reference/api/requests/clan_war_log.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan_war_log
diff --git a/docs/API Reference/api/requests/clan_warleagues_wars.md b/docs/API Reference/api/requests/clan_warleagues_wars.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.clan_warleagues_wars
diff --git a/docs/API Reference/api/requests/gold_pass.md b/docs/API Reference/api/requests/gold_pass.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.gold_pass
diff --git a/docs/API Reference/api/requests/league.md b/docs/API Reference/api/requests/league.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.league
diff --git a/docs/API Reference/api/requests/league_season.md b/docs/API Reference/api/requests/league_season.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.league_season
diff --git a/docs/API Reference/api/requests/league_seasons.md b/docs/API Reference/api/requests/league_seasons.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.league_seasons
diff --git a/docs/API Reference/api/requests/leagues.md b/docs/API Reference/api/requests/leagues.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.leagues
diff --git a/docs/API Reference/api/requests/location.md b/docs/API Reference/api/requests/location.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.location
diff --git a/docs/API Reference/api/requests/locations.md b/docs/API Reference/api/requests/locations.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.locations
diff --git a/docs/API Reference/api/requests/player.md b/docs/API Reference/api/requests/player.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.player
diff --git a/docs/API Reference/api/requests/player_builder_base_rankings.md b/docs/API Reference/api/requests/player_builder_base_rankings.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.player_builder_base_rankings
diff --git a/docs/API Reference/api/requests/player_labels.md b/docs/API Reference/api/requests/player_labels.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.player_labels
diff --git a/docs/API Reference/api/requests/player_rankings.md b/docs/API Reference/api/requests/player_rankings.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.player_rankings
diff --git a/docs/API Reference/api/requests/war_league.md b/docs/API Reference/api/requests/war_league.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.war_league
diff --git a/docs/API Reference/api/requests/war_leagues.md b/docs/API Reference/api/requests/war_leagues.md
@@ -0,0 +1 @@
+::: pyclasher.api.requests.war_leagues
diff --git a/docs/API Reference/client/client.md b/docs/API Reference/client/client.md
@@ -0,0 +1 @@
+::: pyclasher.client.client
diff --git a/docs/API Reference/client/request_consumer.md b/docs/API Reference/client/request_consumer.md
@@ -0,0 +1 @@
+::: pyclasher.client.request_consumer
diff --git a/docs/API Reference/client/request_queue.md b/docs/API Reference/client/request_queue.md
@@ -0,0 +1 @@
+::: pyclasher.client.request_queue
diff --git a/docs/API Reference/exceptions.md b/docs/API Reference/exceptions.md
@@ -1 +1 @@
-::: pyclasher.exceptions
+::: pyclasher.exceptions
diff --git a/docs/API Reference/utils/exectimer.md b/docs/API Reference/utils/exectimer.md
@@ -0,0 +1 @@
+::: pyclasher.utils.exectimer
diff --git a/docs/API Reference/utils/functions.md b/docs/API Reference/utils/functions.md
@@ -0,0 +1 @@
+::: pyclasher.utils.functions
diff --git a/docs/API Reference/Utils/login.md → docs/API Reference/utils/login.md b/docs/API Reference/Utils/login.md → docs/API Reference/utils/login.md
diff --git a/docs/API Reference/utils/request_methods.md b/docs/API Reference/utils/request_methods.md
@@ -0,0 +1 @@
+::: pyclasher.utils.request_methods
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -54,6 +54,7 @@ plugins:
  python:
  options:
  show_source: true
+ - awesome-pages
 
 extra:
  version:
@@ -65,3 +66,6 @@ extra:
  - icon: fontawesome/brands/github
  link: https://github.com/201st-Luka/PyClasher
  name: PyClasher on GitHub
+
+watch:
+ - pyclasher
diff --git a/pyclasher/client/client.py b/pyclasher/client/client.py
@@ -24,7 +24,7 @@
 
 class Client:
  """
- this is the class for the ClashOfClans API client
+ ClashOfClans API client
 
  Attributes:
  __instances: the instances of the client
@@ -52,24 +52,38 @@ class Client:
  logger = MISSING
  """Logger that logs the requests"""
 
- def __new__(cls, *args, **kwargs):
+ def __new__(cls, *, tokens=None, **kwargs):
+ """
+ Class method to create a new instance of the Client
+
+ Args:
+ tokens (str | list[str] | None): the Bearer tokens for the authentication of the ClashOfClans API
+ **kwargs: other key word arguments
+
+ Notes:
+ This function checks if all initialised clients do not share a
+ token. If so the ecxeption ``ClientAlreadyInitialised`` is raised.
+
+ Raises:
+ InvalidType
+ ClientAlreadyInitialised
+ """
  if cls.__instances is None:
  cls.__instances = [super().__new__(cls)]
  return cls.__instances[0]
- if 'tokens' in kwargs:
- if isinstance(kwargs['tokens'], str):
- tokens = [kwargs['tokens']]
- elif isinstance(kwargs['tokens'], Iterable):
- tokens = list(kwargs['tokens'])
- else:
- raise InvalidType(kwargs['tokens'],
- (str, Iterable[str]))
- for token in tokens:
- for client in Client.__instances:
- if client.__tokens is not None:
- if token in client.__tokens:
- raise ClientAlreadyInitialised
- continue
+ if isinstance(tokens, str):
+ tokens = [tokens]
+ elif isinstance(tokens, Iterable):
+ tokens = list(tokens)
+ else:
+ raise InvalidType(tokens,
+ (str, Iterable[str]))
+ for token in tokens:
+ for client in Client.__instances:
+ if client.__tokens is not None:
+ if token in client.__tokens:
+ raise ClientAlreadyInitialised
+ continue
 
  cls.__instances.append(super().__new__(cls))
  return cls.__instances[-1]
@@ -87,7 +101,7 @@ def __init__(
 
  Args:
  tokens (str | list[str] | None): the Bearer tokens for the authentication of the ClashOfClans API
- requests_per_second (int=5):  This integer limits the number of requests done per second (per token).
+ requests_per_second (int): This integer limits the number of requests done per second (per token).
  This value is important to bypass the rate limit of the ClashOfClans API.
  More tokens allow more requests per second because each token can do
  as many requests per second as specified.
@@ -151,7 +165,7 @@ async def from_login(cls, email, password, requests_per_second=5,
 
  logger.info("initialising client via login")
 
- self = cls([login.temporary_api_token for login in logins],
+ self = cls(tokens=[login.temporary_api_token for login in logins],
  requests_per_second=requests_per_second,
  request_timeout=request_timeout,
  swagger_url=logins[0].swagger_url)

diff --git a/requirements-docs.txt b/requirements-docs.txt
@@ -1,4 +1,5 @@
 mkdocs
 mkdocs-material
 mkdocs-git-committers-plugin
-mkdocstrings[python]
+mkdocstrings[python]
+mkdocs-awesome-pages-plugin