docs for ExApp UI (#175)

During the release there was a deadline and there was no time for
documentation - fixing it now.

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

Author: bigcat88

Makefile

@@ -6,6 +6,10 @@ docs html:
 	rm -rf docs/_build
 	$(MAKE) -C docs html
 
+.PHONY: links
+links:
+	$(MAKE) -C docs links
+
 .PHONY: help
 help:
 	@echo "Welcome to NC_PY_API development. Please use \`make <target>\` where <target> is one of"

README.md

@@ -46,8 +46,9 @@ 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 [AppAPI](https://github.com/cloud-py-api/app_api) to allow
-applications to impersonate users through a separate authentication mechanism.
+It uses [AppAPI](https://github.com/cloud-py-api/app_api) to provide additional functionality allowing
+applications have their own graphical interface, fulfill requests from different users,
+and everything else that is necessary to implement full-fledged applications.
 
 Both classes offer most of the same APIs,
 but NextcloudApp has a broader selection since applications typically require access to more APIs.

docs/Makefile

@@ -7,6 +7,7 @@ SPHINXOPTS	  =
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
+LINKCHECKDIR  = _build/linkcheck
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -22,3 +23,7 @@ github:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: links
+links:
+	@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(LINKCHECKDIR)" $(ALLSPHINXOPTS)

docs/NextcloudApp.rst

@@ -37,6 +37,25 @@ The API will not fail, and in such cases, it will simply re-register without err
 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.
 
+Dockerfile
+----------
+
+We decided to keep all the examples and applications in the same format as the usual PHP applications for Nextcloud.
+
+.. code-block::
+
+    ADD cs[s] /app/css
+    ADD im[g] /app/img
+    ADD j[s] /app/js
+    ADD l10[n] /app/l10n
+    ADD li[b] /app/lib
+
+This code from dockerfile copies folders of app if they exists to the docker container.
+
+**nc_py_api** will automatically mount ``css``, ``img``, ``js``, ``l10n`` folders to the FastAPI.
+
+.. note:: If you do not want automatic mount happen, pass ``map_app_static=False`` to ``set_handlers``.
+
 Debugging
 ---------
 
@@ -54,6 +73,7 @@ Here they are:
 
 * APP_ID - ID of the application.
 * APP_PORT - Port on which application listen for the requests from the Nextcloud.
+* APP_HOST - "0.0.0.0"/"127.0.0.1"/other host value.
 * APP_SECRET - Shared secret between Nextcloud and Application.
 * APP_VERSION - Version of the application.
 * AA_VERSION - Version of the AppAPI.
@@ -67,17 +87,17 @@ After launching your application, execute the following command in the Nextcloud
 
     php occ app_api: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}" \
-        --force-scopes
+        --force-scopes --wait-finish
 
 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>`_ ,
-`TalkBot <https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/talk_bot/Makefile>`_
+`TalkBot <https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/talk_bot/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>`_
+`UiExample <https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/ui_example/Makefile>`_
 
 During the execution of `php occ app_api:app:register`, the **enabled_handler** will be called
 
@@ -201,6 +221,6 @@ into a standard :py:class:`~nc_py_api.files.FsNode` class that describes the fil
 In the **convert_video_to_gif** function, a standard conversion using ``OpenCV`` from a video file to a GIF image occurs,
 and since this is not directly related to working with NextCloud, we will skip this for now.
 
-**ToGif** example `full source <https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/to_gif/src/main.py>`_ code.
+**ToGif** example `full source <https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/to_gif/lib/main.py>`_ code.
 
 This chapter ends here, but the next topics are even more intriguing.

docs/NextcloudTalkBot.rst

@@ -70,6 +70,6 @@ Currently, bots have access only to three methods:
 All other rules and algorithms remain consistent with regular external applications.
 
 Full source of bot example can be found here:
-`TalkBot <https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/talk_bot/src/main.py>`_
+`TalkBot <https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/talk_bot/lib/main.py>`_
 
 Wishing success with your Nextcloud bot integration! May the force be with you!

docs/NextcloudUiApp.rst

@@ -0,0 +1,92 @@
+Writing Nextcloud App with UI
+=============================
+
+.. note:: It is advisable to have experience writing PHP applications for Nextcloud,
+    since the UI of applications not written in PHP is exactly the same.
+
+One of the most interesting features is the ability to register a page in the Nextcloud Top Menu.
+
+Full source of UI example can be found here:
+`UiExample <https://github.com/cloud-py-api/nc_py_api/blob/main/examples/as_app/ui_example/lib/main.py>`_
+
+Here we will simply describe in detail what happens in the example.
+
+.. code-block:: python
+
+    if enabled:
+        nc.ui.resources.set_initial_state(
+            "top_menu", "first_menu", "ui_example_state", {"initial_value": "test init value"}
+        )
+        nc.ui.resources.set_script("top_menu", "first_menu", "js/ui_example-main")
+        nc.ui.top_menu.register("first_menu", "UI example", "img/icon.svg")
+
+**set_initial_state** is analogue of PHP ``OCP\AppFramework\Services\IInitialState::provideInitialState``
+
+**set_script** is analogue of PHP ``Util::addScript``
+
+There is also **set_style** (``Util::addStyle``) that can be used for CSS files and works the same way as **set_script**.
+
+Backend
+-------
+
+.. code-block:: python
+
+    class Button1Format(BaseModel):
+        initial_value: str
+
+
+    @APP.post("/verify_initial_value")
+    async def verify_initial_value(
+        _nc: typing.Annotated[NextcloudApp, Depends(nc_app)],
+        input1: Button1Format,
+    ):
+        print("Old value: ", input1.initial_value)
+        return responses.JSONResponse(content={"initial_value": str(random.randint(0, 100))}, status_code=200)
+
+
+    class FileInfo(BaseModel):
+        getlastmodified: str
+        getetag: str
+        getcontenttype: str
+        fileid: int
+        permissions: str
+        size: int
+        getcontentlength: int
+        favorite: int
+
+
+    @APP.post("/nextcloud_file")
+    async def nextcloud_file(
+        _nc: typing.Annotated[NextcloudApp, Depends(nc_app)],
+        args: dict,
+    ):
+        print(args["file_info"])
+        return responses.Response()
+
+Here is defining two endpoints for test purposes.
+
+The first is to get the current initial state of the page when the button is clicked.
+
+Second one is receiving a default information about file in the Nextcloud.
+
+Frontend
+--------
+
+The frontend part is the same as the default Nextcloud apps, with slightly different URL generation since all requests are sent through the AppAPI.
+
+JS Frontend part is covered by AppAPI documentation: ``to_do``
+
+Important notes
+---------------
+
+We do not call ``top_menu.unregister`` or ``resources.delete_script`` as during uninstalling of application **AppAPI** will automatically remove this.
+
+.. note:: Recommended way is to manually clean all stuff and probably if it was not an example, we would call all unregister and cleanup stuff during ``disabling``.
+
+
+All resources of ExApp should be avalaible and mounted to webserver(**FastAPI** + **uvicorn** are used by default for this).
+
+.. note:: This is in case you have custom folders that Nextcloud instance should have access.
+
+
+*P.S.: If you are missing some required stuff for the UI part, please inform us, and we will consider adding it.*

docs/index.rst

@@ -25,19 +25,20 @@ and handle complex problems through issues.
 Have a great time with Python and Nextcloud!
 
 .. toctree::
-   :maxdepth: 1
-
-   Installation
-   FirstSteps
-   MoreAPIs
-   NextcloudApp
-   NextcloudTalkBot
-   NextcloudTalkBotTransformers
-   NextcloudSysApp
-   Options
-   reference/index.rst
-   DevSetup
-   benchmarks/AppAPI.rst
+    :maxdepth: 1
+
+    Installation
+    FirstSteps
+    MoreAPIs
+    NextcloudApp
+    NextcloudTalkBot
+    NextcloudTalkBotTransformers
+    NextcloudSysApp
+    NextcloudUiApp
+    Options
+    reference/index.rst
+    DevSetup
+    benchmarks/AppAPI.rst
 
 Indices and tables
 ==================