Merge pull request #228 from napse-invest/feature/mkdocstring

Feature/mkdocstring
napse-invest · Nov 28, 2023 · ab9a009 · ab9a009
2 parents 8f30baa + 79df4d7
commit ab9a009
Show file tree

Hide file tree

Showing 25 changed files with 137 additions and 81 deletions.
diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - main
-      - feature/mkdocs
 
 permissions:
   contents: write
@@ -17,7 +16,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
       with:
-        ref: ${{ github.event.pull_request.head.sha || github.ref }}
+        python-version: 3.11
 
     - name: Set up python
       uses: actions/setup-python@v4
@@ -32,7 +31,7 @@ jobs:
         pip-compile ./requirements/development.txt --output-file ./full-requirements.txt --resolver=backtracking
         pip install -r ./full-requirements.txt
 
-    - name: Lint with ruff
+    - name: Write open-api schema
       run: python tests/test_app/manage.py spectacular --file docs/schema.yml
 
   deploy:

diff --git a/django_napse/api/api_urls.py b/django_napse/api/api_urls.py
@@ -15,8 +15,7 @@ class ConflictingUrlNames(Exception):
 def build_main_router() -> DefaultRouter:
     """Create a main router object and register the appropriate viewsets to it based on the modules and classes found in the `api` directory.
 
-    Returns
-    -------
+    Returns:
         DefaultRouter: The main router object with registered URL patterns.
     """
     main_router = DefaultRouter()

diff --git a/django_napse/core/models/accounts/managers/space.py b/django_napse/core/models/accounts/managers/space.py
@@ -4,6 +4,7 @@
 
 class NapseSpaceManager(models.Manager):
     def create(self, name: str, exchange_account, description: str = ""):
+        """Create a Space instance."""
         SpaceWallet = apps.get_model("django_napse_core", "SpaceWallet")
         SpaceSimulationWallet = apps.get_model("django_napse_core", "SpaceSimulationWallet")
 

diff --git a/django_napse/core/models/accounts/space.py b/django_napse/core/models/accounts/space.py
@@ -11,10 +11,36 @@
 
 
 class NapseSpace(models.Model):
-    """Categorize and manage money."""
+    """Categorize and manage money.
+
+    Attributes:
+        name: Name of the space.
+        uuid: Unique identifier of the space.
+        description: Description of the space.
+        exchange_account: Exchange account of the space.
+        created_at: Date of creation of the space.
+
+
+    Examples:
+        Create a space:
+        ```python
+        import django_napse.core.models import NapseSpace, ExchangeAccount
+
+        exchange_account: ExchangeAccount = ...
+        space = NapseSpace.objects.create(
+            name="Space",
+            description="Space description",
+            exchange_account=exchange_account,
+        )
+        ```
+    """
 
     name = models.CharField(max_length=200)
-    uuid = models.UUIDField(default=uuid.uuid4, editable=False, unique=True)
+    uuid = models.UUIDField(
+        default=uuid.uuid4,
+        editable=False,
+        unique=True,
+    )
     description = models.TextField()
     exchange_account = models.ForeignKey("ExchangeAccount", on_delete=models.CASCADE, related_name="spaces")
     created_at = models.DateTimeField(auto_now_add=True)
@@ -27,8 +53,13 @@ class Meta:
     def __str__(self):
         return f"SPACE: {self.name}"
 
-    def info(self, verbose=True, beacon=""):
-        """Info documentation."""
+    def info(self, verbose: bool = True, beacon: str = "") -> str:
+        """Info documentation.
+
+        Params:
+            verbose: Print to console.
+            beacon: Indentation for printing.
+        """
         string = ""
         string += f"{beacon}Space ({self.pk=}):\n"
         string += f"{beacon}Args:\n"
@@ -43,21 +74,24 @@ def info(self, verbose=True, beacon=""):
         return string
 
     @property
-    def testing(self):
-        """Testing property documentation."""
+    def testing(self) -> bool:
+        """Testing property."""
         return self.exchange_account.testing
 
     @property
     def value(self) -> float:
+        """Value market of space's wallet."""
         connections = self.wallet.connections.all()
         return sum([connection.wallet.value_market() for connection in connections])
 
     @property
     def fleets(self) -> models.QuerySet:
+        """Fleets of the space."""
         connections = self.wallet.connections.all()
         return Fleet.objects.filter(clusters__links__bot__connections__in=connections).distinct()
 
-    def get_stats(self) -> dict:
+    def get_stats(self) -> dict[str, int | float | str]:
+        """Statistics of space."""
         order_count_30 = Order.objects.filter(
             connection__in=self.wallet.connections.all(),
             created_at__gt=datetime.now(tz=get_default_timezone()) - timedelta(days=30),
@@ -70,6 +104,7 @@ def get_stats(self) -> dict:
         }
 
     def delete(self) -> None:
+        """Delete space."""
         if self.testing:
             return super().delete()
         if self.value > 0:

diff --git a/django_napse/core/models/bots/controller.py b/django_napse/core/models/bots/controller.py
@@ -257,8 +257,7 @@ def _get_price(self) -> float:
 
         Always calls the exchange API. (Can be costly)
 
-        Returns
-        -------
+        Returns:
         float: The price of the pair.
         """
         exchange_controller = self.exchange_controller
@@ -284,9 +283,8 @@ def get_price(self) -> float:
 
         Only updates the price if it is older than 1 minute.
 
-        Returns
-        -------
-        float: The price of the pair.
+        Returns:
+            price: The price of the pair.
         """
         if self.last_price_update is None or self.last_price_update < datetime.now(tz=timezone.utc) - timedelta(minutes=1):
             self._get_price()

diff --git a/django_napse/core/tasks/base_tasks.py b/django_napse/core/tasks/base_tasks.py
@@ -19,9 +19,8 @@ def run(self):
     def create_task(self) -> None:
         """Build task feed_bots_with_candles.
 
-        Raises
-        ------
-        ValidationError: if task already exist
+        Raises:
+            ValidationError: if task already exist
         """
         try:
             schedule = IntervalSchedule.objects.get(every=self.interval_time, period=IntervalSchedule.SECONDS)
@@ -38,9 +37,8 @@ def create_task(self) -> None:
     def delete_task(self) -> None:
         """Destroy task feed_bots_with_candles.
 
-        Raises
-        ------
-        ValidationError: if task doesn't exist
+        Raises:
+            ValidationError: if task doesn't exist
         """
         try:
             PeriodicTask.objects.get(task=self.name).delete()

diff --git a/django_napse/simulations/models/datasets/dataset.py b/django_napse/simulations/models/datasets/dataset.py
@@ -74,8 +74,7 @@ def create_candles(self, candles: list):
     def set_downloading(self):
         """Set the dataset status to downloading.
 
-        Raises
-        ------
+        Raises:
             ValueError: If the dataset isn't in IDLE status.
         """
         if self.status == DOWNLOAD_STATUS.IDLE:

diff --git a/docs/index.md b/docs/index.md
@@ -1,7 +1,6 @@
 
-![Napse logo](theme/assets/napse_invest_logo_black.svg#only-light)
-![Napse logo](theme/assets/napse_invest_logo_white.svg#only-dark)
-
+![Napse logo](theme/assets/napse_invest_logo_black.svg#only-light){ width="500" : .center}
+![Napse logo](theme/assets/napse_invest_logo_white.svg#only-dark){ width="500" : .center}
 <h1 align="center">
 
 </h1><br>
@@ -65,4 +64,4 @@ exchange_account_query = ExchangeAccount.objects.all()
 
 django-napse is compatible with a few exchanges (for now):
 
-- [Binance]()
+- [Binance](https://www.binance.com/en)
diff --git a/docs/sources/reference/bots.md b/docs/sources/reference/bots.md
diff --git a/docs/sources/reference/connections.md b/docs/sources/reference/connections.md
diff --git a/docs/sources/reference/exchanges.md b/docs/sources/reference/exchanges.md
diff --git a/docs/sources/reference/fleets.md b/docs/sources/reference/fleets.md
diff --git a/docs/sources/reference/histories.md b/docs/sources/reference/histories.md
diff --git a/docs/sources/reference/keys.md b/docs/sources/reference/keys.md
diff --git a/docs/sources/reference/orders.md b/docs/sources/reference/orders.md
diff --git a/docs/sources/reference/permissions.md b/docs/sources/reference/permissions.md
diff --git a/docs/sources/reference/space.md b/docs/sources/reference/space.md
diff --git a/docs/sources/reference/spaces.md b/docs/sources/reference/spaces.md
@@ -0,0 +1,7 @@
+# Space
+## Space's Model
+::: django_napse.core.models.NapseSpace
+
+---
+## Space's manager
+::: django_napse.core.models.accounts.managers.NapseSpaceManager
diff --git a/docs/sources/reference/transactions.md b/docs/sources/reference/transactions.md
diff --git a/docs/sources/reference/wallets.md b/docs/sources/reference/wallets.md
diff --git a/docs/theme/assets/stylesheets/extra.css b/docs/theme/assets/stylesheets/extra.css
@@ -1 +1,5 @@
 
+.center {
+    display: block;
+    margin: 0 auto;
+}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -4,14 +4,26 @@ repo_name: napse-invest/django-napse
 repo_url: https://github.com/napse-invest/django-napse
 copyright: MIT Licence
 
-
 docs_dir: "docs/"
 
-
 extra_css:
-  -  assets/stylesheets/extra.css
-  -  assets/stylesheets/api.css
+  -  theme/assets/stylesheets/extra.css
+  -  theme/assets/stylesheets/api.css
 
+extra:
+  social:
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/NapseInvest
+      name: X
+    - icon: fontawesome/brands/linkedin
+      link: https://fr.linkedin.com/company/napse-investment
+      name: Linkedin
+    - icon: fontawesome/brands/discord
+      link: https://discord.com/invite/47gKBreSXa
+      name: Discord
+    - icon: fontawesome/brands/github
+      link: https://github.com/napse-invest/Napse
+      name: Github
 
 theme:
   name: 'material'
@@ -34,7 +46,7 @@ theme:
     - media: "prefers-color-scheme: dark"
       scheme: slate
       primary: teal
-      accent: blue grey
+      accent: teal
       toggle:
         # icon: material/toggle-switch-off-outline
         icon: material/toggle-switch
@@ -57,7 +69,8 @@ theme:
     - search.suggest
 
 plugins:
-  - search
+  - search 
+  - autorefs
   - inline-svg
   - coverage:
       page_name: coverage  # default
@@ -67,47 +80,50 @@ plugins:
   - mkdocstrings:
       default_handler: python
       handlers:
-        python:
-          paths: [src]
+        python: 
+          paths: [.] 
+          options: 
+            show_source: false
+            allow_inspection: false 
+            show_bases: false 
+            show_root_heading: false 
+            docstring_style: google 
+            docstring_section_style: list
+            docstring_options:
+              ignore_init_summary: false
+              trim_doctest_flags: true
+            heading_level: 3
+  # Contributors
+  - neoteroi.contribs:
+      contributors:
+          - email: [email protected]
+            image: https://avatars.githubusercontent.com/u/11559668?s=400&u=6564188698fbd519f21b7f400e522659e41a158e&v=4
+
 
 markdown_extensions:
   - toc:
-      permalink: "#"
+      permalink: "#" 
   - pymdownx.snippets:
   - pymdownx.magiclink:
   - attr_list:
   - md_in_html:
-  - pymdownx.highlight:
-      anchor_linenums: true
   - pymdownx.inlinehilite:
   - pymdownx.superfences:
-  - pymdownx.keys:
+  - pymdownx.keys: 
   - pymdownx.tasklist:
-      custom_checkbox: true
+      custom_checkbox: true 
   - admonition
-  - codehilite:
+  - codehilite:  
       use_pygments: true
       noclasses: true
       pygments_style: tango
   - pymdownx.details:
   - pymdownx.tabbed:
       alternate_style: true
-
-
-extra:
-  social:
-    - icon: fontawesome/brands/twitter
-      link: https://twitter.com/NapseInvest
-      name: X
-    - icon: fontawesome/brands/linkedin
-      link: https://fr.linkedin.com/company/napse-investment
-      name: Linkedin
-    - icon: fontawesome/brands/discord
-      link: https://discord.com/invite/47gKBreSXa
-      name: Discord
-    - icon: fontawesome/brands/github
-      link: https://github.com/napse-invest/Napse
-      name: Github
+  - pymdownx.highlight:
+      anchor_linenums: true
+      # line_spans: __span
+      # pygments_lang_class: true
 
 nav:
   - Home: 
@@ -118,7 +134,17 @@ nav:
     - "sources/guides/space.md"
     - "sources/guides/fleet.md"
   - Reference:
-    - "sources/reference/space.md"
+    - "sources/reference/bots.md"
+    - "sources/reference/connections.md"
+    - "sources/reference/exchanges.md"
+    - "sources/reference/fleets.md"
+    - "sources/reference/histories.md"
+    - "sources/reference/keys.md"
+    - "sources/reference/orders.md"
+    - "sources/reference/permissions.md"
+    - "sources/reference/spaces.md"
+    - "sources/reference/transactions.md"
+    - "sources/reference/wallets.md"
   - API: "api.md"
   - Development: 
     - Contributing: "contributing.md"

diff --git a/pyproject.toml b/pyproject.toml
@@ -49,7 +49,7 @@ exclude = [
     "migrations",
 ]
 
-# pydocstyle.convention ="google"
+pydocstyle.convention ="google"
 # Same as Black.
 line-length = 150
 

diff --git a/requirements/development.txt b/requirements/development.txt
@@ -19,6 +19,4 @@ neoteroi-mkdocs==1.0.4              # https://github.com/Neoteroi/mkdocs-plugins
 drf-spectacular==0.26.5             # https://github.com/tfranzel/drf-spectacular
 mkdocstrings==0.24.0                # https://github.com/mkdocstrings/mkdocstrings
 mkdocstrings-python==1.7.5          # https://github.com/mkdocstrings/python
-# pyyaml==6.0.1                       # https://github.com/yaml/pyyaml
-# uritemplate==4.1.1                  # https://github.com/python-hyper/uritemplate
-# pymdown-extensions==10.5.1          # https://github.com/facelessuser/pymdown-extensions
+