more docs (#91)

Signed-off-by: Alexander Piskun <bigcat88@icloud.com>

AUTHORS

@@ -4,6 +4,7 @@ answer newbie questions, and generally made NC-Py-API that much better:
 
     Andrey Borysenko <andrey18106x@gmail.com>
     Alexander Piskun <bigcat88@icloud.com>
+    CooperGerman <https://github.com/CooperGerman>
     <Please alphabetize new entries>
 
 A big THANK YOU goes to:

README.md

@@ -1,3 +1,7 @@
+<p align="center">
+    <img src="https://raw.githubusercontent.com/cloud-py-api/nc_py_api/docs/resources/logo_py_nc.png" alt="NcPyApi logo">
+</p>
+
 # Official Nextcloud Python Framework
 
 [![Analysis & Coverage](https://github.com/cloud-py-api/nc_py_api/actions/workflows/analysis-coverage.yml/badge.svg)](https://github.com/cloud-py-api/nc_py_api/actions/workflows/analysis-coverage.yml)
@@ -11,22 +15,42 @@
 
 Python library that provides a robust and well-documented API that allows developers to interact with and extend Nextcloud's functionality.
 
-### Basic Features:
- * Operations with Files and Folders
- * ~~Operations with Trash bin and File versions~~
- * Operations with Users and User Groups
- * User status
- * Weather status
- * Notifications support
- * Shares support
- * ~~Talk support~~
-
-### Extended Features with AppEcosystemV2:
- * Defining callback routes with `FastAPI` for Nextcloud
- * Registering UI elements in Nextcloud
- * Storing logs to the `nextcloud.log` file
- * Get/save key-value pairs in AppConfigEx/PreferencesEx tables.
- * **Tons of the cool stuff that is coming soon**
+### The key features are:
+ * **Fast**: High performance, and as low-latency as possible.
+ * **Intuitive**: Fast to code, easy to use.
+ * **Reliable**: Minimum number of incompatible changes.
+ * **Robust**: All code is covered with tests as much as possible.
+ * **Easy**: Designed to be easy to use with excellent documentation.
+
+### Capabilities
+| **_Capability_** | Nextcloud 26 | Nextcloud 27 | Nextcloud 28 |
+|------------------|:------------:|:------------:|:------------:|
+| Filesystem*      |      ✅       |      ✅       |      ✅       |
+| Shares           |      ✅       |      ✅       |      ✅       |
+| Users & Groups   |      ✅       |      ✅       |      ✅       |
+| User status      |      ✅       |      ✅       |      ✅       |
+| Weather status   |      ✅       |      ✅       |      ✅       |
+| Notifications    |      ✅       |      ✅       |      ✅       |
+| Nextcloud Talk   |      ❌       |      ❌       |      ❌       |
+| Text Provider**  |      ❌       |      ❌       |      ❌       |
+
+&ast;missing `Trash bin` and `File version` support.<br>
+&ast;&ast;available only for NextcloudApp
+
+### Differences between the NextCloud and NextCloudApp classes
+
+The **NextCloud** class functions as a standard NextCloud client,
+enabling you to make API requests using a username and password.
+
+On the other hand, the **NextCloudApp** class is designed for creating applications for NextCloud.<br>
+It uses the [AppEcosystem](https://github.com/cloud-py-api/app_ecosystem_v2) to allow
+applications to impersonate users through a separate authentication mechanism.
+
+Both classes offer most of the same APIs,
+but NextCloudApp has a broader selection since applications typically require access to more APIs.
+
+Any code written for the NextCloud class can easily be adapted for use with the NextCloudApp class,
+as long as it doesn't involve calls that require user password verification.
 
 ### Support
 
@@ -37,19 +61,31 @@ You can support us in several ways:
 - 💁 Resolve some Issue or create a Pull Request (contribute to this project)
 - 🙏 Write an example of its use or correct a typo in the documentation.
 
-### 🚀 How to start
-
-In a very close near future we will publish examples
-
-### More Information
+## More Information
 
 - [Documentation](https://cloud-py-api.github.io/nc_py_api/)
   - [First steps](https://cloud-py-api.github.io/nc_py_api/FirstSteps.html)
-  - [Writing a simple Nextcloud application](to-do)
-  - [Writing a Nextcloud System Application](to-do)
+  - [More APIs](https://cloud-py-api.github.io/nc_py_api/MoreAPIs.html)
+  - [Writing a simple Nextcloud application](https://cloud-py-api.github.io/nc_py_api/NextcloudApp.html)
+  - [Writing a Nextcloud System Application](https://cloud-py-api.github.io/nc_py_api/NextcloudSysApp.html)
 - [Examples](https://github.com/cloud-py-api/nc_py_api/tree/main/examples)
 - [Contribute](https://github.com/cloud-py-api/nc_py_api/blob/main/.github/CONTRIBUTING.md)
   - [Discussions](https://github.com/cloud-py-api/nc_py_api/discussions)
   - [Issues](https://github.com/cloud-py-api/nc_py_api/issues)
   - [Setting up dev environment](https://cloud-py-api.github.io/nc_py_api/DevSetup.html)
 - [Changelog](https://github.com/cloud-py-api/nc_py_api/blob/main/CHANGELOG.md)
+
+### Motivation
+
+_Python's language, elegant and clear,_<br>
+_Weaves logic's threads without fear,_<br>
+_And in the sky, where clouds take form,_<br>
+_Nextcloud emerges, a digital norm._<br>
+
+_Together they stand, a duo bright,_<br>
+_Python and Nextcloud, day and night,_<br>
+_In a digital dance, they guide and sail,_<br>
+_Shaping tomorrow, where new ideas prevail._<br>
+
+#### **Know that we are always here to support and assist you on your journey.**
+### P.S: **_Good luck, and we hope you have fun!_**

docs/FirstSteps.rst

@@ -7,14 +7,12 @@ For this part, you will need an environment with **nc_py_api** installed and Nex
 
 Full support is only available from version ``27.1`` of Nextcloud.
 
-Nextcloud client
-^^^^^^^^^^^^^^^^
 
 .. note:: In many cases, even if you want to develop an application,
     it's a good idea to first debug and develop part of it as a client.
 
-Creation
-""""""""
+Creating Nextcloud client class
+"""""""""""""""""""""""""""""""
 
 .. code-block:: python
 
@@ -92,3 +90,11 @@ Example of using ``file.find()`` to search for file objects.
 .. note:: We welcome the idea of how to make the definition of search queries more friendly.
 
 .. literalinclude:: ../examples/as_client/files/find.py
+
+Conclusion
+""""""""""
+
+Once you have a good understanding of working with files, you can move on to more APIs.
+
+You don't have to learn them all at the same time, but it's good to at least have a general idea, so let's go with
+:ref:`more-apis`!

docs/MoreAPIs.rst

@@ -0,0 +1,4 @@
+.. _more-apis:
+
+More APIs
+=========

docs/NextcloudApp.rst

@@ -0,0 +1,98 @@
+Writing a Nextcloud Application
+===============================
+
+This chapter assumes that you are already familiar with the `concepts <https://cloud-py-api.github.io/app_ecosystem_v2/Concepts.html>`_ of the AppEcosystem.
+
+As a first step, let's take a look at the structure of a basic Python application.
+
+Skeleton
+--------
+
+.. literalinclude:: ../examples/as_app/skeleton/src/main.py
+
+What's going on in the skeleton?
+
+First, it's important to understand that an external application acts more like a microservice, with its endpoints being called by Nextcloud.
+
+Therefore, when the application receives a request at the endpoint ``/enable``,
+it should register all its functionalities in the cloud and wait for requests from Nextcloud.
+
+.. note:: This doesn't apply to system applications, which will be covered in the next chapter.
+
+So, calling:
+
+.. code-block:: python
+
+    set_handlers(APP, enabled_handler)
+
+will register an **enabled_handler** that will be called **both when the application is enabled and disabled**.
+
+During the enablement process, you should register all the functionalities that your application offers
+in the **enabled_handler** and remove them during the disablement process.
+
+The API is designed so that you don't have to check whether an endpoint is already registered
+(e.g., in case of a malfunction or if the administrator manually altered something in the Nextcloud database).
+The API will not fail, and in such cases, it will simply re-register without error.
+
+If any error prevents your application from functioning, you should provide a brief description in the return instead
+of an empty string, and log comprehensive information that will assist the administrator in addressing the issue.
+
+Debugging
+---------
+
+Debugging an application within Docker and rebuilding it from scratch each time can be cumbersome.
+Therefore, a manual deployment option has been specifically designed for this purpose.
+
+First register ``manual_install`` daemon:
+
+.. code-block:: shell
+
+    php occ app_ecosystem_v2:daemon:register manual_install "Manual Install" manual-install 0 0 0
+
+Then, launch your application. Since this is a manual deployment, it's your responsibility to set minimum of the environment variables.
+Here they are:
+
+* APP_ID - ID of the application.
+* APP_PORT - Port on which application listen for the requests from the Nextcloud.
+* APP_SECRET - Secret for ``hmac`` signature generation.
+* APP_VERSION - Version of the application.
+* AE_VERSION - Version of the AppEcosystem.
+* NEXTCLOUD_URL - URL at which the application can access the Nextcloud API.
+
+You can find values for these environment variables in the **Skeleton** or **ToGif** run configurations.
+
+After launching your application, execute the following command in the Nextcloud container:
+
+.. code-block:: shell
+
+    php occ app_ecosystem_v2:app:register YOUR_APP_ID manual_install --json-info \
+        "{\"appid\":\"YOUR_APP_ID\",\"name\":\"YOUR_APP_DISPLAY_NAME\",\"daemon_config_name\":\"manual_install\",\"version\":\"YOU_APP_VERSION\",\"secret\":\"YOUR_APP_SECRET\",\"host\":\"host.docker.internal\",\"scopes\":{\"required\":[2, 10, 11],\"optional\":[30, 31, 32, 33]},\"port\":SELECTED_PORT,\"protocol\":\"http\",\"system_app\":0}" \
+        -e --force-scopes
+
+You can see how **nc_py_api** registers in ``scripts/dev_register.sh``.
+
+It's advisable to write these steps as commands in a Makefile for quick use.
+
+Examples for such Makefiles can be found in this repository:
+`Skeleton <https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/skeleton/Makefile>`_ ,
+`ToGif <https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/to_gif/Makefile>`_ ,
+`nc_py_api <https://github.com/cloud-py-api/nc_py_api/blob/main/scripts/dev_register.sh>`_
+
+During the execution of `php occ app_ecosystem_v2:app:register`, the **enabled_handler** will be called,
+as we pass the flag ``-e``, meaning ``enable after registration``.
+
+This is likely all you need to start debugging and developing an application for Nextcloud.
+
+Pack & Deploy
+-------------
+
+Before reading this chapter, please review the basic information about deployment
+and the currently supported types of
+`deployments configurations <https://cloud-py-api.github.io/app_ecosystem_v2/DeployConfigurations.html>`_ in the AppEcosystem documentation.
+
+to-do
+
+From skeleton to ToGif
+----------------------
+
+to-do

docs/NextcloudSysApp.rst

@@ -0,0 +1,2 @@
+Writing System Nextcloud Application
+====================================

docs/index.rst

@@ -29,6 +29,9 @@ Have a great time with Python and Nextcloud!
 
    Installation
    FirstSteps
+   MoreAPIs
+   NextcloudApp
+   NextcloudSysApp
    Options
    reference/index.rst
    DevSetup

examples/as_app/skeleton/Makefile

@@ -43,6 +43,7 @@ run27:
 
 .PHONY: manual_register
 manual_register:
+	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:unregister skeleton --silent || true
 	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:register skeleton manual_install --json-info \
   "{\"appid\":\"skeleton\",\"name\":\"App Skeleton\",\"daemon_config_name\":\"manual_install\",\"version\":\"1.0.0\",\"secret\":\"12345\",\"host\":\"host.docker.internal\",\"port\":9030,\"scopes\":{\"required\":[],\"optional\":[]},\"protocol\":\"http\",\"system_app\":0}" \
   -e --force-scopes

examples/as_app/skeleton/src/main.py

@@ -23,10 +23,14 @@ def enabled_handler(enabled: bool, nc: NextcloudApp) -> str:
     return ""
 
 
+# Of course, you can use `FastAPI lifespan: <https://fastapi.tiangolo.com/advanced/events/#lifespan>` instead of this.
+# The only requirement for the application is to define `/enabled` and `/heartbeat` handlers.
 @APP.on_event("startup")
 def initialization():
     set_handlers(APP, enabled_handler)
 
 
 if __name__ == "__main__":
+    # Wrapper around `uvicorn.run`.
+    # You are free to call it directly, just use `APP_HOST` and `APP_PORT` from the environment.
     run_app("main:APP", log_level="trace")

examples/as_app/to_gif/Makefile

@@ -43,6 +43,7 @@ run27:
 
 .PHONY: manual_register
 manual_register:
+	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:unregister to_gif --silent || true
 	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:register to_gif manual_install --json-info \
   "{\"appid\":\"to_gif\",\"name\":\"to_gif\",\"daemon_config_name\":\"manual_install\",\"version\":\"1.0.0\",\"secret\":\"12345\",\"host\":\"host.docker.internal\",\"port\":9031,\"scopes\":{\"required\":[10],\"optional\":[32]},\"protocol\":\"http\",\"system_app\":0}" \
   -e --force-scopes

nc_py_api/_version.py

@@ -1,3 +1,3 @@
 """Version of nc_py_api."""
 
-__version__ = "0.0.31"
+__version__ = "0.0.32.dev0"

nc_py_api/options.py

@@ -1,6 +1,6 @@
 """Options to change nc_py_api's runtime behavior.
 
-Each setting only affects newly created instances of Nextcloud or NextcloudApp class, unless otherwise specified.
+Each setting only affects newly created instances of **Nextcloud**/**NextcloudApp** class, unless otherwise specified.
 Specifying options in **kwargs** has higher priority than this.
 """
 import typing