From 39db36fdb28e592cbcc6422e946b864bc58de914 Mon Sep 17 00:00:00 2001 From: Christian Wolf Date: Wed, 24 Nov 2021 14:50:02 +0100 Subject: [PATCH] Fixed some more links in the dev manual Signed-off-by: Christian Wolf --- developer_manual/app_development/intro.rst | 2 +- developer_manual/app_development/tutorial.rst | 24 +++++++++---------- developer_manual/basics/controllers.rst | 10 ++++---- .../basics/dependency_injection.rst | 2 +- developer_manual/basics/events.rst | 4 ++-- developer_manual/basics/middlewares.rst | 2 +- developer_manual/basics/request_lifecycle.rst | 4 ++-- developer_manual/basics/routing.rst | 2 +- .../client_apis/android_library/index.rst | 2 +- developer_manual/digging_deeper/rest_apis.rst | 2 +- .../getting_started/codingguidelines.rst | 2 +- .../prologue/bugtracker/codereviews.rst | 2 +- 12 files changed, 29 insertions(+), 29 deletions(-) diff --git a/developer_manual/app_development/intro.rst b/developer_manual/app_development/intro.rst index 34a5b9d1d..6f034836e 100644 --- a/developer_manual/app_development/intro.rst +++ b/developer_manual/app_development/intro.rst @@ -7,7 +7,7 @@ Create an app .. sectionauthor:: Bernhard Posselt -After :doc:`you've set up the development environment <../general/devenv>` change into the Nextcloud apps directory:: +After :doc:`you've set up the development environment <../getting_started/devenv>` change into the Nextcloud apps directory:: cd /var/www/nextcloud/apps diff --git a/developer_manual/app_development/tutorial.rst b/developer_manual/app_development/tutorial.rst index 22de45de2..af3e6976e 100644 --- a/developer_manual/app_development/tutorial.rst +++ b/developer_manual/app_development/tutorial.rst @@ -10,7 +10,7 @@ This tutorial will outline how to create a very simple notes app. The finished a Setup ----- -First the :doc:`development environment <../general/devenv>` needs to be set up. This can be done by either `downloading the zip from the website `_ or cloning it directly from GitHub:: +First the :doc:`development environment <../getting_started/devenv>` needs to be set up. This can be done by either `downloading the zip from the website `_ or cloning it directly from GitHub:: git clone git@github.com:nextcloud/server.git --branch $BRANCH cd server @@ -92,9 +92,9 @@ On the server side we need to register a callback that is executed once the requ ['name' => 'page#index', 'url' => '/', 'verb' => 'GET'] ]]; -This route calls the controller **OCA\\notestutorial\\PageController->index()** method which is defined in **notestutorial/lib/Controller/PageController.php**. The controller returns a :doc:`template `, in this case **notestutorial/templates/main.php**: +This route calls the controller **OCA\\notestutorial\\PageController->index()** method which is defined in **notestutorial/lib/Controller/PageController.php**. The controller returns a :doc:`template <../basics/front-end/templates>`, in this case **notestutorial/templates/main.php**: -.. note:: @NoAdminRequired and @NoCSRFRequired in the comments above the method turn off security checks, see :doc:`../basics/controllers` +.. note:: **@NoAdminRequired** and **@NoCSRFRequired** in the comments above the method turn off security checks, see `Authentication on Controllers <../basics/controllers.html#authentication>`__ .. code-block:: php @@ -221,7 +221,7 @@ Database -------- Now that the routes are set up and connected the notes should be saved in the -database. To do that first create a :doc:`database migration ` +database. To do that first create a :doc:`database migration <../basics/storage/migrations>` by creating a file **notestutorial/lib/Migration/VersionXXYYZZDateYYYYMMDDHHSSAA.php**, so for example **notestutorial/lib/Migration/Version000000Date20181013124731.php**"" @@ -280,9 +280,9 @@ To create the tables in the database, run the :ref:`migration ` in **notestutorial/appinfo/info.xml** . migration will be executed when user reload page after app upgrade +.. note:: To trigger the table creation/alteration when user updating the app, update the :doc:`version tag ` in **notestutorial/appinfo/info.xml** . migration will be executed when user reload page after app upgrade -.. note:: to be able to access the occ migrations commands, please enable the debug flag in config.php +.. note:: To be able to access the occ migrations commands, please enable the debug flag in config.php .. code-block:: xml @@ -302,7 +302,7 @@ To create the tables in the database, run the :ref:`migration -Now that the tables are created we want to map the database result to a PHP object to be able to control data. First create an :doc:`entity ` in **notestutorial/lib/Db/Note.php**: +Now that the tables are created we want to map the database result to a PHP object to be able to control data. First create an :doc:`entity <../basics/storage/database>` in **notestutorial/lib/Db/Note.php**: .. code-block:: php @@ -337,7 +337,7 @@ Now that the tables are created we want to map the database result to a PHP obje We also define a **jsonSerializable** method and implement the interface to be able to transform the entity to JSON easily. -Entities are returned from so-called :doc:`Mappers `. Let's create one in **notestutorial/lib/Db/NoteMapper.php** and add a **find** and **findAll** method: +Entities are returned from so-called :doc:`Mappers <../basics/storage/database>`. Let's create one in **notestutorial/lib/Db/NoteMapper.php** and add a **find** and **findAll** method: .. code-block:: php @@ -388,7 +388,7 @@ Connect database & controllers The mapper which provides the database access is finished and can be passed into the controller. -You can pass in the mapper by adding it as a type hinted parameter. Nextcloud will figure out how to :doc:`assemble them by itself `. Additionally we want to know the userId of the currently logged in user. Simply add a **$UserId** parameter to the constructor (case sensitive!). To do that open **notestutorial/lib/Controller/NoteController.php** and change it to the following: +You can pass in the mapper by adding it as a type hinted parameter. Nextcloud will figure out how to :doc:`assemble them by itself <../basics/dependency_injection>`. Additionally we want to know the userId of the currently logged in user. Simply add a **$UserId** parameter to the constructor (case sensitive!). To do that open **notestutorial/lib/Controller/NoteController.php** and change it to the following: .. code-block:: php @@ -723,7 +723,7 @@ Unit tests A unit test is a test that tests a class in isolation. It is very fast and catches most of the bugs, so we want many unit tests. -Because Nextcloud uses :doc:`Dependency Injection ` to assemble your app, it is very easy to write unit tests by passing mocks into the constructor. A simple test for the update method can be added by adding this to **notestutorial/tests/Unit/Controller/NoteControllerTest.php**: +Because Nextcloud uses :doc:`Dependency Injection <../basics/dependency_injection>` to assemble your app, it is very easy to write unit tests by passing mocks into the constructor. A simple test for the update method can be added by adding this to **notestutorial/tests/Unit/Controller/NoteControllerTest.php**: .. code-block:: php @@ -943,7 +943,7 @@ To run the integration tests change into the **notestutorial** directory and run Adding a RESTful API (optional) ------------------------------- -A :doc:`RESTful API ` allows other apps such as Android or iPhone apps to access and change your notes. Since syncing is a big core component of Nextcloud it is a good idea to add (and document!) your own RESTful API. +A :doc:`RESTful API <../digging_deeper/rest_apis>` allows other apps such as Android or iPhone apps to access and change your notes. Since syncing is a big core component of Nextcloud it is a good idea to add (and document!) your own RESTful API. Because we put our logic into the **NoteService** class it is very easy to reuse it. The only pieces that need to be changed are the annotations which disable the CSRF check (not needed for a REST call usually) and add support for `CORS `_ so your API can be accessed from other webapps. @@ -1084,7 +1084,7 @@ Since the **NoteApiController** is basically identical to the **NoteController** Building the frontend --------------------- -To create a modern webapp you need to write :doc:`JavaScript`. You can use any JavaScript framework, but this tutorial focusses on a simple frontend using Vue.js. For a more detailed introduction to Vue.js please head over to the `official documentation `_. +To create a modern webapp you need to write :doc:`JavaScript<../basics/front-end/js>`. You can use any JavaScript framework, but this tutorial focusses on a simple frontend using Vue.js. For a more detailed introduction to Vue.js please head over to the `official documentation `_. The source files of our frontend will be stored in the **src/** directory. We use webpack for bundling the files and output of that will be stored in **js/notestutorial.js**. diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst index 238927ef7..6b94e3a9c 100644 --- a/developer_manual/basics/controllers.rst +++ b/developer_manual/basics/controllers.rst @@ -4,7 +4,7 @@ Controllers .. sectionauthor:: Bernhard Posselt -Controllers are used to connect :doc:`routes ` with app logic. Think of it as callbacks that are executed once a request has come in. Controllers are defined inside the **lib/Controller/** directory. +Controllers are used to connect :doc:`routes ` with app logic. Think of it as callbacks that are executed once a request has come in. Controllers are defined inside the **lib/Controller/** directory. To create a controller, simply extend the Controller class and create a method that should be executed on a request: @@ -58,7 +58,7 @@ Getting request parameters Parameters can be passed in many ways: -* Extracted from the URL using curly braces like **{key}** inside the URL (see :doc:`routes`) +* Extracted from the URL using curly braces like **{key}** inside the URL (see :doc:`routing`) * Appended to the URL as a GET request (e.g. ?something=true) * application/x-www-form-urlencoded from a form or jQuery * application/json from a POST, PATCH or PUT request @@ -435,7 +435,7 @@ Because returning values works fine in case of a success but not in case of fail Templates ^^^^^^^^^ -A :doc:`template <../view/templates>` can be rendered by returning a TemplateResponse. A TemplateResponse takes the following parameters: +A :doc:`template ` can be rendered by returning a TemplateResponse. A TemplateResponse takes the following parameters: * **appName**: tells the template engine in which app the template should be located * **templateName**: the name of the template inside the template/ folder without the .php extension @@ -685,7 +685,7 @@ The following policy for instance allows images, audio and videos from other dom OCS ^^^ -.. note:: This is purely for compatibility reasons. If you are planning to offer an external API, go for a :doc:`api` instead. +.. note:: This is purely for compatibility reasons. If you are planning to offer an external API, go for a :doc:`../digging_deeper/rest_apis` instead. In order to ease migration from OCS API routes to the App Framework, an additional controller and response have been added. To migrate your API you can use the **OCP\\AppFramework\\OCSController** base class and return your data in the form of a DataResponse in the following way: @@ -778,7 +778,7 @@ Most of the time though it makes sense to also allow normal users to access the To turn off checks the following *Annotations* can be added before the controller: * **@NoAdminRequired**: Also users that are not admins can access the page -* **@NoCSRFRequired**: Don't check the CSRF token (use this wisely since you might create a security hole; to understand what it does see :doc:`../../general/security`) +* **@NoCSRFRequired**: Don't check the CSRF token (use this wisely since you might create a security hole; to understand what it does see `CSRF in the security section <../prologue/security.html#cross-site-request-forgery>`__) * **@PublicPage**: Everyone can access the page without having to log in A controller method that turns off all checks would look like this: diff --git a/developer_manual/basics/dependency_injection.rst b/developer_manual/basics/dependency_injection.rst index 25c7ae838..1246fcb45 100644 --- a/developer_manual/basics/dependency_injection.rst +++ b/developer_manual/basics/dependency_injection.rst @@ -139,7 +139,7 @@ How the container works The container works in the following way: -* :doc:`A request comes in and is matched against a route ` (for the AuthorController in this case) +* :doc:`A request comes in and is matched against a route ` (for the AuthorController in this case) * The matched route queries **AuthorController** service from the container:: return new AuthorController( diff --git a/developer_manual/basics/events.rst b/developer_manual/basics/events.rst index 52bcbac29..6f6d167af 100644 --- a/developer_manual/basics/events.rst +++ b/developer_manual/basics/events.rst @@ -679,7 +679,7 @@ Hooks .. sectionauthor:: Bernhard Posselt -Hooks are used to execute code before or after an event has occurred. This is for instance useful to run cleanup code after users, groups or files have been deleted. Hooks should be registered in the :doc:`app.php `: +Hooks are used to execute code before or after an event has occurred. This is for instance useful to run cleanup code after users, groups or files have been deleted. Hooks should be registered in the :doc:`app.php <../app_development/init>`: .. code-block:: php @@ -689,7 +689,7 @@ Hooks are used to execute code before or after an event has occurred. This is fo $app = new Application(); $app->getContainer()->query('UserHooks')->register(); -The hook logic should be in a separate class that is being registered in the :doc:`requests/container`: +The hook logic should be in a separate class that is being registered in the `App contructor `__: .. code-block:: php diff --git a/developer_manual/basics/middlewares.rst b/developer_manual/basics/middlewares.rst index 689e81d60..684220925 100644 --- a/developer_manual/basics/middlewares.rst +++ b/developer_manual/basics/middlewares.rst @@ -34,7 +34,7 @@ To generate your own middleware, simply inherit from the Middleware class and ov } -The middleware can be registered in the :doc:`container` and added using the **registerMiddleware** method: +The middleware can be registered in the :doc:`dependency_injection` and added using the **registerMiddleware** method: .. code-block:: php diff --git a/developer_manual/basics/request_lifecycle.rst b/developer_manual/basics/request_lifecycle.rst index 5f75036c3..2aa6e7ca9 100644 --- a/developer_manual/basics/request_lifecycle.rst +++ b/developer_manual/basics/request_lifecycle.rst @@ -11,7 +11,7 @@ A typical HTTP request consists of the following: * **A Method**: e.g. GET * **Request headers**: e.g. Accept: application/json -The following sections will present an overview over how that request is being processed to provide an in depth view over how Nextcloud works. If you are not interested in the internals or don't want to execute anything before and after your controller, feel free to skip this section and continue directly with defining :doc:`your app's routes `. +The following sections will present an overview over how that request is being processed to provide an in depth view over how Nextcloud works. If you are not interested in the internals or don't want to execute anything before and after your controller, feel free to skip this section and continue directly with defining :doc:`your app's routes `. Front controller ---------------- @@ -22,7 +22,7 @@ In the beginning, all requests are sent to Nextcloud's :file:`index.php` which i * Filesystem * Logging -The type of the app is determined by inspecting the app's :doc:`configuration file <../info>` (:file:`appinfo/info.xml`). Loading apps means that the :doc:`main file <../app_development/init>` (:file:`appinfo/app.php`) of each installed app is being loaded and executed. That means that if you want to execute code before a specific app is being run, you can place code in your app's :doc:`../app_development/init` file. +The type of the app is determined by inspecting the app's :doc:`configuration file <../app_development/info>` (:file:`appinfo/info.xml`). Loading apps means that the :doc:`main file <../app_development/init>` (:file:`appinfo/app.php`) of each installed app is being loaded and executed. That means that if you want to execute code before a specific app is being run, you can place code in your app's :doc:`../app_development/init` file. Afterwards the following steps are performed: diff --git a/developer_manual/basics/routing.rst b/developer_manual/basics/routing.rst index 802210db5..c2097522c 100644 --- a/developer_manual/basics/routing.rst +++ b/developer_manual/basics/routing.rst @@ -190,7 +190,7 @@ Sometimes it is useful to turn a route into a URL to make the code independent f } -URLGenerator is case sensitive, so **appName** must match **exactly** the name you use in :doc:`configuration <../storage/configuration>`. +URLGenerator is case sensitive, so **appName** must match **exactly** the name you use in :doc:`configuration <../basics/storage/configuration>`. If you use a CamelCase name as *myCamelCaseApp*, .. code-block:: php diff --git a/developer_manual/client_apis/android_library/index.rst b/developer_manual/client_apis/android_library/index.rst index ca51d2e93..b72ec526a 100644 --- a/developer_manual/client_apis/android_library/index.rst +++ b/developer_manual/client_apis/android_library/index.rst @@ -19,7 +19,7 @@ setup and process of contribution is `documented here `_. You might want to start with doing one or two `good first issues `_ -to get into the code and note our :doc:`../general/index`. +to get into the code and note our :doc:`../../prologue/index`. For authentication, you can use our usual login flow, and in addition (or instead if you are OK for users to depend on our Files app) use the great diff --git a/developer_manual/digging_deeper/rest_apis.rst b/developer_manual/digging_deeper/rest_apis.rst index 636a9ffe9..caae8c1f3 100644 --- a/developer_manual/digging_deeper/rest_apis.rst +++ b/developer_manual/digging_deeper/rest_apis.rst @@ -4,7 +4,7 @@ REST APIs .. sectionauthor:: Bernhard Posselt -Offering a RESTful API is not different from creating a :doc:`route ` and :doc:`controllers ` for the web interface. It is recommended though to inherit from ApiController and add **@CORS** annotations to the methods so that `web applications will also be able to access the API `_. +Offering a RESTful API is not different from creating a :doc:`route <../basics/routing>` and :doc:`controllers <../basics/controllers>` for the web interface. It is recommended though to inherit from ApiController and add **@CORS** annotations to the methods so that `web applications will also be able to access the API `_. .. code-block:: php diff --git a/developer_manual/getting_started/codingguidelines.rst b/developer_manual/getting_started/codingguidelines.rst index 3567ee23b..f16ea078f 100644 --- a/developer_manual/getting_started/codingguidelines.rst +++ b/developer_manual/getting_started/codingguidelines.rst @@ -30,7 +30,7 @@ The most important labels and their meaning: * #design - this needs help from the design team or is a design-related issue/pull request * #technical debt - this issue or PR is about `technical debt `_ * #good first issue - these are issues which are relatively easy to solve and ideal for people who want to learn how to code in Nextcloud -* #needs info - this issue needs further information from the reporter, see :doc:`../bugtracker/triaging` +* #needs info - this issue needs further information from the reporter, see :doc:`../../prologue/bugtracker/triaging` * #high #medium #low signify how important the bug is. * Tags showing the state of the issue or PR, numbered 0-4: diff --git a/developer_manual/prologue/bugtracker/codereviews.rst b/developer_manual/prologue/bugtracker/codereviews.rst index 060fa6ca8..6d6f37296 100644 --- a/developer_manual/prologue/bugtracker/codereviews.rst +++ b/developer_manual/prologue/bugtracker/codereviews.rst @@ -45,7 +45,7 @@ How will it work? Examples -------- -Read our documentation about :doc:`../general/codingguidelines` for information +Read our documentation about :doc:`../../getting_started/codingguidelines` for information on what a good pull request and good Nextcloud code looks like. These are two examples that are considered to be good examples of how pull