small documentation update (#77)

* set up dev environment stuff

---------

Signed-off-by: Alexander Piskun <[email protected]>

Author: bigcat88

.github/CONTRIBUTING.md

@@ -9,19 +9,15 @@ Please send a pull request to the `main` branch.  Feel free to ask questions [vi
 
 - Fork the nc_py_api repository.
 - Create a new branch from `main`.
-- Install dev requirements with `pip install ".[dev]"`
-- Develop bug fixes, features, tests, etc.
-- Most of the tests are designed to run from under the GitHub actions. If you want to run them locally, see this [guide](to-do)
-- Install `pylint` locally, it will run during `pre-commit`.
-- Install `pre-commit` hooks by `pre-commit install` command.
+- Set up development environment as described in a [Setting up dev environment](https://cloud-py-api.github.io/nc_py_api/DevSetup.html)
 - Create a pull request to pull the changes from your branch to the nc_py_api `main`.
 
 ### Guidelines
 
 - Separate code commits from reformatting commits.
 - Where possible, provide tests for any newly added code.
 - Follow PEP 8.
-- Update CHANGELOG.md as needed or appropriate with your bug fixes, feature additions and tests.
+- Update CHANGELOG.md as needed or appropriate with your bug fixes, feature additions, and tests.
 
 ## Security vulnerabilities
 

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.0.29 - 2023-08-14]
+## [0.0.29 - 2023-08-13]
 
 ### Added
 

README.md

@@ -51,5 +51,5 @@ In a very close near future we will publish 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](to-do)
+  - [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)

docs/DevSetup.rst

@@ -0,0 +1,59 @@
+Setting up dev environment
+==========================
+
+We highly recommend to use `Julius Haertl docker setup <https://github.com/juliushaertl/nextcloud-docker-dev>`_ for Nextcloud dev setup.
+
+Development of `nc-py-api` can be done on any OS as it is a **pure** Python package.
+
+Suggested IDE: **PyCharm**, but of course you can use any IDE you like for this like **VS Code** or **Vim**.
+
+Steps to setup up the development environment:
+
+#. Setup Nextcloud locally or remotely.
+#. Install `AppEcosystem <https://github.com/cloud-py-api/app_ecosystem_v2>`_, follow it's steps to register ``deploy daemon`` if needed.
+#. Clone the `nc_py_api <https://github.com/cloud-py-api/nc_py_api>`_ with :command:`shell`::
+
+    git clone https://github.com/cloud-py-api/nc_py_api.git
+
+#. Set current working dir to the root folder of cloned **nc_py_api** with :command:`shell`::
+
+    cd nc_py_api
+
+#. Create and activate Virtual Environment with :command:`shell`::
+
+    python3 -m venv env
+
+#. Activate Python Virtual Environment with :command:`shell`::
+
+    source ./env/bin/activate
+
+#. Update ``pip`` to the last version with :command:`pip`::
+
+    python3 -m pip install --upgrade pip
+
+#. Install dev-dependencies with :command:`pip`::
+
+    pip install ".[dev]"
+
+#. Install `pre-commit` hooks with :command:`shell`::
+
+    pre-commit install
+
+#. If ``deploy daemon`` is registered for AppEcosystem, register **nc_py_api** as an application with :command:`shell`::
+
+    make register28
+
+#. In ``tests/gfixture.py`` edit ``NC_AUTH_USER`` and ``NC_AUTH_PASS``, if they are different in your setup.
+#. Run tests to check that everything works with :command:`shell`::
+
+    python3 -m pytest
+
+#. Install documentation dependencies if needed with :command:`pip`::
+
+    pip install ".[docs]"
+
+#. You can easy build documentation with :command:`shell`::
+
+    make docs
+
+#. **Your setup is ready for the developing nc_py_api and Applications based on it. Best of Luck!**

docs/FirstSteps.rst

@@ -43,7 +43,7 @@ Getting list of files of User
 
 This is a hard way to get list of all files recursively:
 
-.. literalinclude:: ../examples/as_client/files_listing.py
+.. literalinclude:: ../examples/as_client/files/listing.py
 
 This code do the same in one DAV call, but prints **directories** in addition to files:
 
@@ -73,7 +73,7 @@ Uploading a single file
 It is always better to use ``upload_stream`` instead of ``upload`` as it works
 with chunks and ``in future`` will support **multi threaded** upload.
 
-.. literalinclude:: ../examples/as_client/files_upload.py
+.. literalinclude:: ../examples/as_client/files/upload.py
 
 Downloading a single file
 """""""""""""""""""""""""
@@ -82,4 +82,4 @@ A very simple example of downloading an image as one piece of data to memory and
 
 .. note:: For big files, it is always better to use ``download2stream`` method, as it uses chunks.
 
-.. literalinclude:: ../examples/as_client/files_download.py
+.. literalinclude:: ../examples/as_client/files/download.py

docs/Installation.rst

@@ -3,19 +3,23 @@ Installation
 
 First it is always a good idea to update ``pip`` to the latest version with :command:`pip`::
 
-    python3 -m pip install --upgrade pip
+    python -m pip install --upgrade pip
 
 To use it as a simple Nextcloud client install it without any additional dependencies with :command:`pip`::
 
-    python3 -m pip install --upgrade nc_py_api
+    python -m pip install --upgrade nc_py_api
 
 To use in the Nextcloud Application mode install it with additional ``app`` dependencies with :command:`pip`::
 
-    python3 -m pip install --upgrade "nc_py_api[app]"
+    python -m pip install --upgrade "nc_py_api[app]"
 
 To join the development of **nc_py_api** api install development dependencies with :command:`pip`::
 
-    python3 -m pip install --upgrade "nc_py_api[dev]"
+    python -m pip install --upgrade "nc_py_api[dev]"
+
+Or install last dev-version from GitHub with :command:`pip`::
+
+    python -m pip install --upgrade "nc_py_api[dev] @ git+https://github.com/cloud-py-api/nc_py_api"
 
 Congratulations, the next chapter :ref:`first-steps` awaits.
 

docs/index.rst

@@ -31,6 +31,7 @@ Have a great time with Python and Nextcloud!
    FirstSteps
    Options
    reference/index.rst
+   DevSetup
    benchmarks/AppEcosystem.rst
 
 Indices and tables

docs/reference/Files/Files.rst

@@ -2,7 +2,7 @@ File System
 ===========
 
 The Files API is universal for both modes and provides all the necessary methods for working with the Nextcloud file system.
-Refer to the **fs examples** to see how to use them nicely.
+Refer to the `Files examples <https://github.com/cloud-py-api/nc_py_api/tree/main/examples/as_client/files>`_ to see how to use them nicely.
 
 All File APIs are designed to work relative to the current user.
 

docs/reference/Files/Shares.rst

@@ -2,7 +2,7 @@ File Sharing
 ============
 
 The Shares API is universal for both modes and provides all the necessary methods for working with the Nextcloud Shares system.
-Refer to the **share examples** to see how to use them nicely.
+Refer to the `Sharing examples <https://github.com/cloud-py-api/nc_py_api/tree/main/examples/as_client/sharing>`_ to see how to use them nicely.
 
 .. autoclass:: nc_py_api.files.sharing._FilesSharingAPI
     :members:

examples/as_app/to_gif/main.py

@@ -85,9 +85,9 @@ def enabled_handler(enabled: bool, nc: NextcloudApp) -> str:
     print(f"enabled={enabled}")
     try:
         if enabled:
-            nc.gui.files_dropdown_menu.register("to_gif", "TO GIF", "/video_to_gif", mime="video")
+            nc.ui.files_dropdown_menu.register("to_gif", "TO GIF", "/video_to_gif", mime="video")
         else:
-            nc.gui.files_dropdown_menu.unregister("to_gif")
+            nc.ui.files_dropdown_menu.unregister("to_gif")
     except Exception as e:
         return str(e)
     return ""