Merge pull request #89 from doccano/feature/mkdocs

Add workflow to deploy mkdocs site

.github/CODEOWNERS

@@ -1 +1 @@
-* @afparsons @Hironsan
+* @Hironsan

.github/workflows/mkdocs-deployment.yml

@@ -0,0 +1,19 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@1.16
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: docs/mkdocs.yml
+          REQUIREMENTS: docs/requirements.txt

README.md

@@ -23,13 +23,13 @@ pip install doccano-client
 - All methods return a `requests.models.Response` object.
 
 ```python
-from doccano_api_client import DoccanoClient
+from doccano_client import DoccanoClient
 
 # instantiate a client and log in to a Doccano instance
 doccano_client = DoccanoClient(
-    'http://doccano.example.com',
-    'username',
-    'password'
+  'http://doccano.example.com',
+  'username',
+  'password'
 )
 
 # get basic information about the authorized user
@@ -93,4 +93,4 @@ Endpoint Names:
 
 We're introducing a newly revamped Doccano API Client that features more Pythonic interaction as well as more testing and documentation. It also adds more regulated compatibility with specific Doccano release versions.
 
-You can find the documentation on usage of the beta client [here](./doccano_api_client/beta/README.md).
+You can find the documentation on usage of the beta client [here](doccano_client/beta/README.md).

doccano_api_client/beta/README.md → doccano_client/beta/README.md

@@ -9,7 +9,7 @@ Currently tested for compatibility against Doccano v1.5.0-1.5.5.
 The client can be instatiated with a base URL referring to the target Doccano instance. Once instantiated, you can login using your Doccano username and password.
 
 ```python
-from doccano_api_client.beta import DoccanoClient, controllers
+from doccano_client.beta import DoccanoClient, controllers
 
 client = DoccanoClient("your_instance_url_here")
 client.login("my_username", "my_password")

doccano_api_client/beta/controllers/annotation.py → doccano_client/beta/controllers/annotation.py

@@ -43,7 +43,11 @@ def annotations_url(self) -> str:
         return f"{self._example_url}"
 
     def all(self) -> Iterable[AnnotationController]:
-        """Return a sequence of AnnotationControllers."""
+        """Return a sequence of AnnotationControllers.
+
+        Yields:
+            AnnotationController: The next annotation controller.
+        """
         response = self.client_session.get(self.annotations_url)
         verbose_raise_for_status(response)
         annotation_dicts = response.json()["annotations"]

doccano_api_client/beta/controllers/comment.py → doccano_client/beta/controllers/comment.py

@@ -51,7 +51,11 @@ def comments_url(self) -> str:
         return f"{self._parent_url}/comments"
 
     def all(self) -> Iterable[CommentController]:
-        """Return a sequence of Comments for a given controller, which maps to an object"""
+        """Return a sequence of Comments for a given controller, which maps to an object
+
+        Yields:
+            CommentController: The next comment controller.
+        """
         response = self.client_session.get(self.comments_url)
         verbose_raise_for_status(response)
         comment_dicts = response.json()

doccano_api_client/beta/controllers/example.py → doccano_client/beta/controllers/example.py

@@ -93,7 +93,11 @@ def get(self, example_id: int) -> ExampleController:
         )
 
     def all(self, confirmed=None) -> Iterable[ExampleController]:
-        """Return a sequence of Examples for a given controller, which maps to a Project"""
+        """Return a sequence of Examples for a given controller, which maps to a Project
+
+        Yields:
+            ExampleController: The next example controller.
+        """
         response = self.client_session.get(f"{self.examples_url}?confirmed={confirmed}")
 
         while True:

doccano_api_client/beta/controllers/label.py → doccano_client/beta/controllers/label.py

@@ -122,7 +122,11 @@ def labels_url(self) -> str:
         return f"{self._project_url}/labels"
 
     def all(self) -> Iterable[LabelController]:
-        """Return a sequence of all labels for a given controller, which maps to a project"""
+        """Return a sequence of all labels for a given controller, which maps to a project
+
+        Yields:
+            LabelController: The next label controller.
+        """
         response = self.client_session.get(self.labels_url)
         verbose_raise_for_status(response)
         label_dicts = response.json()

doccano_api_client/beta/controllers/project.py → doccano_client/beta/controllers/project.py

@@ -57,7 +57,11 @@ def relation_types(self) -> RelationTypesController:
         return RelationTypesController(self.project_url, self.client_session)
 
     def download(self, api_url: str, only_approved: bool = True) -> Iterable[Any]:
-        """Trigger a download of all approved and labelled texts in jsonl format. It's zipped"""
+        """Trigger a download of all approved and labelled texts in jsonl format. It's zipped
+
+        Yields:
+            binary: The binary data.
+        """
 
         download_json = {"exportApproved": only_approved, "format": "JSONL"}
         responseCreateExportTask = self.client_session.post(
@@ -114,7 +118,11 @@ def get(self, project_id: int) -> ProjectController:
         )
 
     def all(self) -> Iterable[ProjectController]:
-        """Return a sequence of projects for a given controller, assigned to the user"""
+        """Return a sequence of projects for a given controller, assigned to the user
+
+        Yields:
+            ProjectController: The next project controller.
+        """
         response = self.client_session.get(self.projects_url)
 
         while True:

doccano_api_client/beta/controllers/relation.py → doccano_client/beta/controllers/relation.py

@@ -42,7 +42,11 @@ def relations_url(self) -> str:
         return f"{self._example_url}/relations"
 
     def all(self) -> Iterable[RelationController]:
-        """Return a sequence of RelationControllers."""
+        """Return a sequence of RelationControllers.
+
+        Yields:
+            RelationController: The next relation controller.
+        """
         response = self.client_session.get(self.relations_url)
 
         verbose_raise_for_status(response)

doccano_api_client/beta/controllers/relation_type.py → doccano_client/beta/controllers/relation_type.py

@@ -38,7 +38,11 @@ def relation_types_url(self) -> str:
         return f"{self._project_url}/relation-types"
 
     def all(self) -> Iterable[RelationTypeController]:
-        """Return a sequence of all span-types for a given controller, which maps to a project"""
+        """Return a sequence of all span-types for a given controller, which maps to a project
+
+        Yields:
+            RelationTypeController: The next relation type controller.
+        """
         response = self.client_session.get(self.relation_types_url)
         verbose_raise_for_status(response)
         label_dicts = response.json()

doccano_api_client/beta/controllers/span.py → doccano_client/beta/controllers/span.py

@@ -42,7 +42,11 @@ def spans_url(self) -> str:
         return f"{self._example_url}/spans"
 
     def all(self) -> Iterable[SpanController]:
-        """Return a sequence of SpanControllers."""
+        """Return a sequence of SpanControllers.
+
+        Yields:
+            SpanController: The next span controller.
+        """
         response = self.client_session.get(self.spans_url)
         verbose_raise_for_status(response)
         span_dicts = response.json()

doccano_api_client/beta/controllers/span_type.py → doccano_client/beta/controllers/span_type.py

@@ -38,7 +38,11 @@ def span_types_url(self) -> str:
         return f"{self._project_url}/span-types"
 
     def all(self) -> Iterable[SpanTypeController]:
-        """Return a sequence of all span-types for a given controller, which maps to a project"""
+        """Return a sequence of all span-types for a given controller, which maps to a project
+
+        Yields:
+            SpanTypeController: The next span type controller.
+        """
         response = self.client_session.get(self.span_types_url)
         verbose_raise_for_status(response)
         label_dicts = response.json()

doccano_api_client/beta/models/projects.py → doccano_client/beta/models/projects.py

@@ -51,7 +51,11 @@ class Project(DataClassJsonMixin):
     use_relation: bool = False
 
     def __post_init__(self) -> None:
-        """Propogates resourcetype field based on project_type field, needed for project creation"""
+        """Propogates resourcetype field based on project_type field, needed for project creation
+
+        Raises:
+            AssertionError: If project type is not in resource types.
+        """
         if self.project_type not in PROJECT_TO_RESOURCE_TYPE:
             raise AssertionError(f"project_type not in: {PROJECT_TO_RESOURCE_TYPE.keys()}")
         self.resourcetype = PROJECT_TO_RESOURCE_TYPE.get(self.project_type, "NotAResource")

doccano_api_client/beta/utils/response.py → doccano_client/beta/utils/response.py

@@ -7,8 +7,12 @@ def __init__(self, response: Response):
         super().__init__(str(response.json()), response=response)
 
 
-def verbose_raise_for_status(response: Response) -> None:
-    """Output a bad response's text before raising for verbosity, return response otherwise"""
+def verbose_raise_for_status(response: Response) -> Response:
+    """Output a bad response's text before raising for verbosity, return response otherwise
+
+    Raises:
+        DoccanoAPIError: if request raises HTTPError.
+    """
     try:
         response.raise_for_status()
     except exceptions.HTTPError as err:

doccano_api_client/cli/commands.py → doccano_client/cli/commands.py

@@ -6,9 +6,9 @@
 import sys
 from pathlib import Path
 
-from doccano_api_client.beta import DoccanoClient
-from doccano_api_client.cli.estimators import select_estimator_class
-from doccano_api_client.cli.usecases import build_annotator
+from doccano_client.beta import DoccanoClient
+from doccano_client.cli.estimators import select_estimator_class
+from doccano_client.cli.usecases import build_annotator
 
 DOCCANO_HOME = os.path.expanduser(os.environ.get("DOCCANO_HOME", "~/doccano"))
 Path(DOCCANO_HOME).mkdir(parents=True, exist_ok=True)

doccano_api_client/cli/estimators.py → doccano_client/cli/estimators.py

@@ -2,7 +2,7 @@
 
 from typing import Iterator
 
-from doccano_api_client.cli.entity import Entity
+from doccano_client.cli.entity import Entity
 
 
 class SpaCyEntityEstimator:

doccano_api_client/cli/usecases.py → doccano_client/cli/usecases.py

@@ -6,9 +6,9 @@
 
 from tqdm import tqdm
 
-from doccano_api_client.beta.controllers import ProjectController
-from doccano_api_client.beta.models import Span
-from doccano_api_client.cli.entity import Entity
+from doccano_client.beta.controllers import ProjectController
+from doccano_client.beta.models import Span
+from doccano_client.cli.entity import Entity
 
 
 def load_mapping(filepath: str, encoding="utf-8") -> dict[str, str]:

docs/index.md

@@ -0,0 +1 @@
+# Overview

docs/install.md

@@ -0,0 +1 @@
+# Install

docs/mkdocs.yml

@@ -0,0 +1,35 @@
+# Project information
+site_name: "doccano-client"
+site_description: "A simple client wrapper for doccano API."
+site_author: "Hiroki Nakayama"
+site_url: "https://doccano.github.io/doccano-client/"
+docs_dir: .
+
+# Repository
+repo_name: "doccano/doccano-client"
+repo_url: "https://github.com/doccano/doccano-client"
+
+# Copyright
+copyright: "Copyright © 2018 - 2019 Hiroki Nakayama"
+
+theme:
+  name: "material"
+  palette:
+    primary: "cyan"
+    accent: "cyan"
+  show_sidebar: true
+
+extra:
+  social:
+    - icon: "fontawesome/brands/github"
+      link: "https://github.com/Hironsan"
+    - icon: "fontawesome/brands/twitter"
+      link: "https://twitter.com/Hironsan13"
+
+plugins:
+  - same-dir
+
+# Page tree
+nav:
+  - Overview: index.md
+  - Install: install.md

docs/requirements.txt

@@ -0,0 +1 @@
+mkdocs-same-dir