From a16e6ce58023e6efaab57a82a92f634f3564a554 Mon Sep 17 00:00:00 2001 From: infinityofspace <30715462+infinityofspace@users.noreply.github.com> Date: Sun, 29 Sep 2024 18:44:16 +0200 Subject: [PATCH] updated and improved docs --- Readme.md | 4 +- docs/source/pkb_client.cli.rst | 21 +++++++++++ docs/source/pkb_client.client.rst | 61 +++++++++++++++++++++++++++++++ docs/source/pkb_client.rst | 54 +++------------------------ docs/source/usage.rst | 56 +++++++++++++++++++++++----- 5 files changed, 137 insertions(+), 59 deletions(-) create mode 100644 docs/source/pkb_client.cli.rst create mode 100644 docs/source/pkb_client.client.rst diff --git a/Readme.md b/Readme.md index 155157a..f0ff1bc 100644 --- a/Readme.md +++ b/Readme.md @@ -75,7 +75,7 @@ logged and you don't want to log the API access, then you can also set the envir `PKB_API_SECRET`. If you not specify API key and secret in any way, *pkb-client* asks for a user input. The command line arguments of the API key and secret have the highest priority. -You can see an overview of all usable API methods via the help: +You can see an overview of all usable cli methods via the help: ```commandline pkb-client -h @@ -129,7 +129,7 @@ Remove all existing DNS records of the domain `example.com` and restore the DNS pkb-client -k -s dns-import example.com dns_recods.json clear ``` -*Note:* The import function uses the record ID to distinguish DNS records. +*Note:* The `dns-import` function uses the record ID to distinguish DNS records. ### Notes diff --git a/docs/source/pkb_client.cli.rst b/docs/source/pkb_client.cli.rst new file mode 100644 index 0000000..29fc20f --- /dev/null +++ b/docs/source/pkb_client.cli.rst @@ -0,0 +1,21 @@ +pkb\_client.cli package +======================= + +Submodules +---------- + +pkb\_client.cli.cli module +-------------------------- + +.. automodule:: pkb_client.cli.cli + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: pkb_client.cli + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/pkb_client.client.rst b/docs/source/pkb_client.client.rst new file mode 100644 index 0000000..fd677b1 --- /dev/null +++ b/docs/source/pkb_client.client.rst @@ -0,0 +1,61 @@ +pkb\_client.client package +========================== + +Submodules +---------- + +pkb\_client.client.bind\_file module +------------------------------------ + +.. automodule:: pkb_client.client.bind_file + :members: + :undoc-members: + :show-inheritance: + +pkb\_client.client.client module +-------------------------------- + +.. automodule:: pkb_client.client.client + :members: + :undoc-members: + :show-inheritance: + +pkb\_client.client.dns module +----------------------------- + +.. automodule:: pkb_client.client.dns + :members: + :undoc-members: + :show-inheritance: + +pkb\_client.client.domain module +-------------------------------- + +.. automodule:: pkb_client.client.domain + :members: + :undoc-members: + :show-inheritance: + +pkb\_client.client.forwarding module +------------------------------------ + +.. automodule:: pkb_client.client.forwarding + :members: + :undoc-members: + :show-inheritance: + +pkb\_client.client.ssl\_cert module +----------------------------------- + +.. automodule:: pkb_client.client.ssl_cert + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: pkb_client.client + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/pkb_client.rst b/docs/source/pkb_client.rst index 534a91a..161588e 100644 --- a/docs/source/pkb_client.rst +++ b/docs/source/pkb_client.rst @@ -1,56 +1,14 @@ pkb\_client package =================== -Submodules ----------- +Subpackages +----------- -pkb\_client.cli module ----------------------- +.. toctree:: + :maxdepth: 4 -.. automodule:: pkb_client.cli - :members: - :undoc-members: - :show-inheritance: - -pkb\_client.client module -------------------------- - -.. automodule:: pkb_client.client - :members: - :undoc-members: - :show-inheritance: - -pkb\_client.dns module ----------------------- - -.. automodule:: pkb_client.dns - :members: - :undoc-members: - :show-inheritance: - -pkb\_client.domain module -------------------------- - -.. automodule:: pkb_client.domain - :members: - :undoc-members: - :show-inheritance: - -pkb\_client.forwarding module ------------------------------ - -.. automodule:: pkb_client.forwarding - :members: - :undoc-members: - :show-inheritance: - -pkb\_client.ssl\_cert module ----------------------------- - -.. automodule:: pkb_client.ssl_cert - :members: - :undoc-members: - :show-inheritance: + pkb_client.cli + pkb_client.client Module contents --------------- diff --git a/docs/source/usage.rst b/docs/source/usage.rst index abb7570..10997a1 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -4,8 +4,8 @@ Usage Module ++++++ -The module provides the :class:`PKBClient ` class, which is used to interact with the PKB API. -To use the PKB client, you need to create an instance of the :class:`PKBClient ` class: +The module provides the :class:`PKBClient ` class, which is used to interact with the PKB API. +To use the PKB client, you need to create an instance of the :class:`PKBClient ` class: .. code-block:: python @@ -22,7 +22,7 @@ that require authentication (e.g. to manage dns records of your domains). Moreov defaults to the latest version of the official PKB API endpoint. For example to get the domain pricing, which does not require authentication, you can use the -:func:`get_domain_pricing ` method: +:func:`get_domain_pricing ` method: .. code-block:: python @@ -32,20 +32,58 @@ For example to get the domain pricing, which does not require authentication, yo domain_pricing = pkb.get_domain_pricing() print(domain_pricing) -You can find all available methods in the :class:`PKBClient ` class documentation. +You can find all available methods in the :class:`PKBClient ` class documentation. CLI +++ -The module also provides a CLI to interact with the PKB API. To use the CLI, you need to install the package: +The module also provides a CLI to interact with the PKB API. For example to get the domain pricing, you can use the `get-domain-pricing` command: .. code-block:: bash - pip install pkb_client + pkb-client domain-pricing -This creates the `pkb-client` command, which can be used to interact with the PKB API. -For example to get the domain pricing, you can use the `get-domain-pricing` command: +All available commands can be listed with the `--help` option: .. code-block:: bash - pkb-client domain-pricing + pkb-client --help + +.. code-block:: bash + + usage: cli.py [-h] [-k KEY] [-s SECRET] [--debug] [--endpoint ENDPOINT] + {ping,dns-create,dns-edit,dns-delete,dns-retrieve,dns-export,dns-export-bind,dns-import,dns-import-bind,domain-pricing,ssl-retrieve,dns-servers-update,dns-servers-receive,domains-list,url-forward-retrieve,url-forward-create,url-forward-delete} + ... + + Python client for the Porkbun API + + positional arguments: + {ping,dns-create,dns-edit,dns-delete,dns-retrieve,dns-export,dns-export-bind,dns-import,dns-import-bind,domain-pricing,ssl-retrieve,dns-servers-update,dns-servers-receive,domains-list,url-forward-retrieve,url-forward-create,url-forward-delete} + Supported API methods + ping Ping the API Endpoint + dns-create Create a new DNS record. + dns-edit Edit an existing DNS record. + dns-delete Delete an existing DNS record. + dns-retrieve Get all DNS records. + dns-export Save all DNS records to a local json file. + dns-export-bind Save all DNS records to a local BIND file. + dns-import Restore all DNS records from a local json file. + dns-import-bind Restore all DNS records from a local BIND file. + domain-pricing Get the pricing for Porkbun domains. + ssl-retrieve Retrieve an SSL bundle for given domain. + dns-servers-update Update the DNS servers for a domain. + dns-servers-receive + Retrieve the DNS servers for a domain. + domains-list List all domains in this account in chunks of 1000. + url-forward-retrieve + Retrieve all URL forwards. + url-forward-create Create a new URL forward. + url-forward-delete Delete an existing URL forward. + + options: + -h, --help show this help message and exit + -k KEY, --key KEY The API key used for Porkbun API calls (usually starts with "pk"). + -s SECRET, --secret SECRET + The API secret used for Porkbun API calls (usually starts with "sk"). + --debug Enable debug mode. + --endpoint ENDPOINT The API endpoint to use. \ No newline at end of file