Merge pull request #40 from 201st-Luka/new-features

some docs, guides and stability fixes and features

.github/workflows/docs.yml

@@ -21,4 +21,5 @@ jobs:
  restore-keys: |
  mkdocs-material-
  - run: pip install -r requirements-docs.txt
+ - run: python doc_gen.py
  - run: mkdocs gh-deploy --force

CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+Contributing to this open-source project is appreciated. To contribute please 
+visit the Discord server as well.
+
+---
+
+## Where to start
+
+The contribution starts with an issue. The created issue should explain what to
+do. Based on this issue you can start contributing. If so, refer to the issue in
+the pull request. 
+
+### Issues
+
+The issues must follow these guidelines:
+- An issue must not be a duplicate of an existing issue.
+- A bug issue must provide clear information about the bug.
+- A feature request should contain information about what the feature should do
+and what it serves.
+
+Irrelevant issues, duplicates or issues failing to comply to these guidelines 
+will be closed. 
+
+### Pull requests
+
+After solving the issue it is possible to create a pull request. This pull 
+request must target the `unstable` branch. From there it will be part of the bot 
+in the next release.
+
+Requirements for a pull request are:
+- Commits must be clear
+- The pull request must be up-to-date with the `stable` branch
+- All checks (if applicable) must pass
+- A review must be requested from at least one developer (201st-Luka)
+
+### Recognising the contribution
+
+When the PR is merged in the `stable` branch. GitHub will automatically add the 
+user to the repository's contributor list. It is also possible to earn a role 
+on the Discord server for contribution.
+
+---
+
+## Installation
+
+1. Fork the repository and copy it to your local machine.
+2. Install the requirements:
+ - for developing:
+ - [aiohttp](https://pypi.org/project/aiohttp/) (`pip install aiohttp`)
+
+ You can simply do 
+ ```bash
+ pip install -r requirements.txt
+ ```
+ - for testing:
+ - [aiohttp](https://pypi.org/project/aiohttp/) (`pip install aiohttp`)
+ - [pytest](https://pypi.org/project/pytest/) (`pip install pytest`)
+ - [pytest-asyncio](https://pypi.org/project/pytest-asyncio/) 
+(`pip install pytest-asyncio`)
+ You can simply do
+ ```bash
+ pip install -r requirements-tests.txt
+ ```
+ - for creating the documentation:
+ - [mkdocs](https://pypi.org/project/mkdocs/) (`pip install mkdocs`)
+ - [mkdocs-material](https://pypi.org/project/mkdocs-material/) 
+(`pip install mkdocs-material`)
+ - [mkdocstrings[python]](https://pypi.org/project/mkdocstrings/) 
+(`pip install mkdocstrings[python]`)
+ - [mkdocs-awesome-pages-plugin](https://pypi.org/project/mkdocs-awesome-pages-plugin/) 
+(`pip install mkdocs-awesome-pages-plugin`)
+ You can simply do
+ ```bash
+ pip install -r requirements-docs.txt
+ ```
+ In total, you should have installed 7 packages.
+
+---
+
+You're done! Happy coding.

README.md

@@ -49,6 +49,8 @@ Feel free to contribute to the repository.
 You can fork the repository and commit your changes in a pull request. Please 
 consider to check out the [Discord server][discord_url] if so.
 
+For more information, please see the [CONTRIBUTING.md](CONTRIBUTING.md) file
+
 ---
 
 ## Future

doc_gen.py

@@ -13,10 +13,11 @@ def create_markdown_structure(package_path, output_path):
 
  Args:
  package_path (str): The path to the Python package.
- output_path (str): The path where the directory structure and markdown files will be generated.
+ output_path (str): The path where the directory structure and markdown
+ files will be generated.
  """
- for dirpath, dirnames, filenames in os.walk(package_path):
- relative_dir = os.path.relpath(dirpath, package_path)
+ for dir_path, _, filenames in os.walk(package_path):
+ relative_dir = os.path.relpath(dir_path, package_path)
  output_dir = os.path.join(output_path, relative_dir)
  os.makedirs(output_dir, exist_ok=True)
 
@@ -35,20 +36,34 @@ def create_markdown_structure(package_path, output_path):
  f"{module_name}.md")
 
  with open(markdown_file_path, 'w') as markdown_file:
- print(f"Creating docs for {import_path}")
+ print(f"Creating markdown file for {import_path}")
  markdown_file.write(markdown_content)
 
 
+def copy_contributing(package_path, docs_path):
+ source_file = os.path.join(package_path, "CONTRIBUTING.md")
+ dest_file = os.path.join(docs_path, "CONTRIBUTING.md")
+
+ with open(source_file, 'r') as file:
+ print(f"Reading {source_file}...")
+ contributing = file.read()
+
+ with open(dest_file, 'w') as copy:
+ print(f"Writing {dest_file}...")
+ copy.write(contributing)
+
+
 if __name__ == '__main__':
- project_dir = get_project_dir()
+ project_dir = os.getcwd()
 
  doc_dir = os.path.join(project_dir, "docs")
 
- api_ref_dir = os.path.join(doc_dir, "docs/API Reference")
+ api_ref_dir = os.path.join(doc_dir, "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)
+ copy_contributing(project_dir, doc_dir)

docs/.pages

@@ -0,0 +1,7 @@
+nav:
+ - Home: index.md
+ - API Reference: API Reference
+ - Contributing:
+ - CONTRIBUTING.md
+ - contributors.md
+ - Tutorials: Tutorials

docs/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+Contributing to this open-source project is appreciated. To contribute please 
+visit the Discord server as well.
+
+---
+
+## Where to start
+
+The contribution starts with an issue. The created issue should explain what to
+do. Based on this issue you can start contributing. If so, refer to the issue in
+the pull request. 
+
+### Issues
+
+The issues must follow these guidelines:
+- An issue must not be a duplicate of an existing issue.
+- A bug issue must provide clear information about the bug.
+- A feature request should contain information about what the feature should do
+and what it serves.
+
+Irrelevant issues, duplicates or issues failing to comply to these guidelines 
+will be closed. 
+
+### Pull requests
+
+After solving the issue it is possible to create a pull request. This pull 
+request must target the `unstable` branch. From there it will be part of the bot 
+in the next release.
+
+Requirements for a pull request are:
+- Commits must be clear
+- The pull request must be up-to-date with the `stable` branch
+- All checks (if applicable) must pass
+- A review must be requested from at least one developer (201st-Luka)
+
+### Recognising the contribution
+
+When the PR is merged in the `stable` branch. GitHub will automatically add the 
+user to the repository's contributor list. It is also possible to earn a role 
+on the Discord server for contribution.
+
+---
+
+## Installation
+
+1. Fork the repository and copy it to your local machine.
+2. Install the requirements:
+ - for developing:
+ - [aiohttp](https://pypi.org/project/aiohttp/) (`pip install aiohttp`)
+
+ You can simply do 
+ ```bash
+ pip install -r requirements.txt
+ ```
+ - for testing:
+ - [aiohttp](https://pypi.org/project/aiohttp/) (`pip install aiohttp`)
+ - [pytest](https://pypi.org/project/pytest/) (`pip install pytest`)
+ - [pytest-asyncio](https://pypi.org/project/pytest-asyncio/) 
+(`pip install pytest-asyncio`)
+ You can simply do
+ ```bash
+ pip install -r requirements-tests.txt
+ ```
+ - for creating the documentation:
+ - [mkdocs](https://pypi.org/project/mkdocs/) (`pip install mkdocs`)
+ - [mkdocs-material](https://pypi.org/project/mkdocs-material/) 
+(`pip install mkdocs-material`)
+ - [mkdocstrings[python]](https://pypi.org/project/mkdocstrings/) 
+(`pip install mkdocstrings[python]`)
+ - [mkdocs-awesome-pages-plugin](https://pypi.org/project/mkdocs-awesome-pages-plugin/) 
+(`pip install mkdocs-awesome-pages-plugin`)
+ You can simply do
+ ```bash
+ pip install -r requirements-docs.txt
+ ```
+ In total, you should have installed 7 packages.
+
+---
+
+You're done! Happy coding.

docs/Tutorials/01_installation.md

@@ -0,0 +1,13 @@
+# Installation
+
+## Requirements
+
+To use the [PyClasher](../index.md)-package you need Python 3.8 or higher.
+
+## Installation
+
+The package is accessible on [PyPi.org](https://pypi.org) so you can install the package 
+using 
+```bash
+pip install pyclasher
+```

docs/Tutorials/11_setting_up_a_Client.md

@@ -0,0 +1,94 @@
+# Setting up a Client
+
+The [Client][client_ref]
+is the heard of this package. It allows to make the requests.
+
+## The client
+
+The [Client][client_ref] uses API tokens that you can obtain from the official
+[ClashOfClans developer portal](https://developer.clashofclans.com/#/). Those tokens serve as a verification to 
+the ClashOfClans API. It is sufficient to create an account and create one or
+multiple tokens. 
+
+## Setting up
+
+### With tokens
+
+To set up a client, you need to import the [Client][client_ref] from 
+`pyclasher.client` and adding the tokens to it:
+
+```python
+import asyncio
+
+from pyclasher.client import Client
+
+
+my_tokens = [
+ "enter your first token here",
+ "enter the other tokens here separated as strings in a list"
+]
+
+my_client = Client(tokens=my_tokens)
+
+async def main():
+ # starting the client
+ await my_client.start()
+
+ # doing requests here
+ ...
+
+ # stopping the client
+ await my_client.close()
+
+asyncio.run(main())
+```
+
+!!! note
+ It is recommended to use environment variables for the tokens. So you can 
+ make sure that the tokens are never leaked on the Internet or on GitHub, ...
+
+### With ClashOfClans developer account
+
+It is also possible to set up a client using the login data from 
+https://developer.clashofclans.com/#/login.
+
+```python
+import asyncio
+
+from pyclasher.client import Client
+
+
+my_email = "email@example.com"
+my_password = "examplePassword1234"
+
+async def login():
+ return await Client.from_login(
+ my_email, my_password,
+ login_count=1 # this parameter is used to log in multiple times to the 
+ # ClashOfClans developer portal and create multiple tokens
+ )
+
+async def main():
+ my_client = await login()
+
+ # starting the client
+ await my_client.start()
+
+ # requests
+ ...
+
+ # stopping the client
+ await my_client.close()
+```
+
+!!! warning
+ This is an alternative method to get tokens. Those tokens are temporarily 
+ and expire after one hour. It is intended for testing purpose only.
+ An implementation to renew the tokens after one hour will not ever happen.
+ Use [tokens](#with-tokens) for production purpose.
+
+
+
+<!---links--->
+[client_ref]: ../API%20Reference/client/client.md#pyclasher.client.client.Client
+

docs/Tutorials/12_Requests.md

@@ -0,0 +1,7 @@
+# Requests
+
+The requests defined in this package are a user-friendly implementation of 
+requesting and getting data of the official ClashOfClans-API. The requests
+return models that are some kind of wrapper for the data that hides behind the 
+models. Those models have error handling and are easier to use than raw JSON
+data.

docs/contributors.md

@@ -0,0 +1,9 @@
+# Contributors
+
+## Project owner
+
+- [201st-Luka](https://github.com/201st-Luka)
+
+## Contributors
+
+No contributors yet. In the future, contributors are going to be added here.

mkdocs.yml

@@ -42,10 +42,6 @@ theme:
 plugins:
  - search:
  lang: en
- - git-committers:
- repository: 201st-Luka/PyClasher
- branch: master
- token: !!python/object/apply:os.getenv ["MKDOCS_GIT_COMMITTERS_APIKEY"]
  - mkdocstrings:
  enabled: true
  custom_templates: templates
@@ -56,6 +52,9 @@ plugins:
  show_source: true
  - awesome-pages
 
+markdown_extensions:
+ - admonition
+
 extra:
  version:
  provider: mike
@@ -68,4 +67,4 @@ extra:
  name: PyClasher on GitHub
 
 watch:
- - pyclasher
+ - pyclasher