From a35392aa6488369815f143122eb3893a4e30e707 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Molakvo=C3=A6=20=28skjnldsv=29?= Date: Wed, 28 Nov 2018 11:59:09 +0100 Subject: [PATCH] Fix linking and rst errors for dev manual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: John Molakvoæ (skjnldsv) --- developer_manual/app/hooks.rst | 2 +- developer_manual/app/index.rst | 7 +++++ developer_manual/app/init.rst | 2 +- developer_manual/app/requests/container.rst | 2 +- developer_manual/app/requests/controllers.rst | 4 +-- developer_manual/app/requests/index.rst | 6 ++--- developer_manual/app/requests/routes.rst | 3 ++- developer_manual/app/testing.rst | 2 +- developer_manual/app/tutorial.rst | 26 +++++++++---------- developer_manual/app/view/templates.rst | 2 +- developer_manual/general/security.rst | 4 +-- 11 files changed, 34 insertions(+), 26 deletions(-) diff --git a/developer_manual/app/hooks.rst b/developer_manual/app/hooks.rst index a09c7c9e0..1182b6da6 100644 --- a/developer_manual/app/hooks.rst +++ b/developer_manual/app/hooks.rst @@ -14,7 +14,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:`container`: +The hook logic should be in a separate class that is being registered in the :doc:`requests/container`: .. code-block:: php diff --git a/developer_manual/app/index.rst b/developer_manual/app/index.rst index 48dbedc50..71d91e465 100644 --- a/developer_manual/app/index.rst +++ b/developer_manual/app/index.rst @@ -10,6 +10,13 @@ App development requests/index view/index storage/index + appdata + changelog + classloader + code_signing + info + init + publishing users two-factor-provider hooks diff --git a/developer_manual/app/init.rst b/developer_manual/app/init.rst index b07dbc3d7..6c71ee757 100644 --- a/developer_manual/app/init.rst +++ b/developer_manual/app/init.rst @@ -35,7 +35,7 @@ The :file:`appinfo/app.php` is the first file that is loaded and executed in Nex \OCP\Util::connectHook('OC_User', 'pre_deleteUser', 'OCA\MyApp\Hooks\User', 'deleteUser'); -Although it is also possible to include :doc:`js` or :doc:`css` for other apps by placing the **addScript** or **addStyle** functions inside this file, it is strongly discouraged, because the file is loaded on each request (also such requests that do not return HTML, but e.g. json or webdav). +Although it is also possible to include :doc:`view/js` or :doc:`view/css` for other apps by placing the **addScript** or **addStyle** functions inside this file, it is strongly discouraged, because the file is loaded on each request (also such requests that do not return HTML, but e.g. json or webdav). .. code-block:: php diff --git a/developer_manual/app/requests/container.rst b/developer_manual/app/requests/container.rst index b28d9d613..18c094b81 100644 --- a/developer_manual/app/requests/container.rst +++ b/developer_manual/app/requests/container.rst @@ -120,7 +120,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/app/requests/controllers.rst b/developer_manual/app/requests/controllers.rst index cd16135e9..1e9055ccc 100644 --- a/developer_manual/app/requests/controllers.rst +++ b/developer_manual/app/requests/controllers.rst @@ -459,7 +459,7 @@ Because returning values works fine in case of a success but not in case of fail Templates ^^^^^^^^^ -A :doc:`template ` can be rendered by returning a TemplateResponse. A TemplateResponse takes the following parameters: +A :doc:`template <../view/templates>` 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 @@ -802,7 +802,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 :doc:`../../general/security`) * **@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/app/requests/index.rst b/developer_manual/app/requests/index.rst index 1a904e042..ee63c2602 100644 --- a/developer_manual/app/requests/index.rst +++ b/developer_manual/app/requests/index.rst @@ -7,7 +7,7 @@ Request lifecycle routes middleware - containers + container controllers api @@ -31,11 +31,11 @@ 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 ` (:file:`appinfo/info.xml`). Loading apps means that the :doc:`main file ` (: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:`init` file. +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 <../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:`../init` file. Afterwards the following steps are performed: * Try to authenticate the user -* Load and execute all the remaining apps' :doc:`init` files +* Load and execute all the remaining apps' :doc:`../init` files * Load and run all the routes in the apps' :file:`appinfo/routes.php` * Execute the router diff --git a/developer_manual/app/requests/routes.rst b/developer_manual/app/requests/routes.rst index b825255fb..7a8113ad3 100644 --- a/developer_manual/app/requests/routes.rst +++ b/developer_manual/app/requests/routes.rst @@ -145,6 +145,7 @@ can be abbreviated by using the **resources** key: ], ]; + Using the URLGenerator ---------------------- @@ -189,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 `. +URLGenerator is case sensitive, so **appName** must match **exactly** the name you use in :doc:`configuration <../storage/configuration>`. If you use a CamelCase name as *myCamelCaseApp*, .. code-block:: php diff --git a/developer_manual/app/testing.rst b/developer_manual/app/testing.rst index 882fb2de5..8d022af2e 100644 --- a/developer_manual/app/testing.rst +++ b/developer_manual/app/testing.rst @@ -23,7 +23,7 @@ When writing your own tests, please ensure that PHPUnit bootstraps from :file:`t PHP classes should be tested by accessing them from the container to ensure that the container is wired up properly. Services that should be mocked can be replaced directly in the container. -A test for the **AuthorStorage** class in :doc:`filesystem`: +A test for the **AuthorStorage** class in :doc:`storage/filesystem`: .. code-block:: php diff --git a/developer_manual/app/tutorial.rst b/developer_manual/app/tutorial.rst index 81f6d9f7b..4cb862ca9 100644 --- a/developer_manual/app/tutorial.rst +++ b/developer_manual/app/tutorial.rst @@ -73,7 +73,7 @@ On the client side we can call these URLs with the following jQuery code: // handle failure }); -On the server side we need to register a callback that is executed once the request comes in. The callback itself will be a method on a :doc:`controller ` and the controller will be connected to the URL with a :doc:`route `. The controller and route for the page are already set up in **ownnotes/appinfo/routes.php**: +On the server side we need to register a callback that is executed once the request comes in. The callback itself will be a method on a :doc:`controller ` and the controller will be connected to the URL with a :doc:`route `. The controller and route for the page are already set up in **ownnotes/appinfo/routes.php**: .. code-block:: php @@ -82,9 +82,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\\OwnNotes\\PageController->index()** method which is defined in **ownnotes/lib/Controller/PageController.php**. The controller returns a :doc:`template `, in this case **ownnotes/templates/main.php**: +This route calls the controller **OCA\\OwnNotes\\PageController->index()** method which is defined in **ownnotes/lib/Controller/PageController.php**. The controller returns a :doc:`template `, in this case **ownnotes/templates/main.php**: -.. note:: @NoAdminRequired and @NoCSRFRequired in the comments above the method turn off security checks, see :doc:`controllers` +.. note:: @NoAdminRequired and @NoCSRFRequired in the comments above the method turn off security checks, see :doc:`requests/controllers` .. code-block:: php @@ -210,7 +210,7 @@ Since those 5 routes are so common, they can be abbreviated by adding a resource 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 schema ` by creating **ownnotes/appinfo/database.xml**: +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 schema ` by creating **ownnotes/appinfo/database.xml**: .. code-block:: xml @@ -276,7 +276,7 @@ To create the tables in the database, the :doc:`version tag ` in **ownnote Reload the page to trigger the database 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 **ownnotes/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 ` in **ownnotes/lib/Db/Note.php**: .. code-block:: php @@ -307,7 +307,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 **ownnotes/lib/Db/NoteMapper.php** and add a **find** and **findAll** method: +Entities are returned from so called :doc:`Mappers `. Let's create one in **ownnotes/lib/Db/NoteMapper.php** and add a **find** and **findAll** method: .. code-block:: php @@ -342,7 +342,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 **ownnotes/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 `. 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 **ownnotes/lib/Controller/NoteController.php** and change it to the following: .. code-block:: php @@ -677,7 +677,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 **ownnotes/tests/Unit/Controller/NoteControllerTest.php**: +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 **ownnotes/tests/Unit/Controller/NoteControllerTest.php**: .. code-block:: php @@ -895,7 +895,7 @@ To run the integration tests change into the **ownnotes** 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 ` 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. @@ -1036,7 +1036,7 @@ Since the **NoteApiController** is basically identical to the **NoteController** Adding JavaScript and CSS ------------------------- -To create a modern webapp you need to write :doc:`JavaScript`. You can use any JavaScript framework but for this tutorial we want to keep it as simple as possible and therefore only include the templating library `handlebarsjs `_. `Download the file `_ into **ownnotes/js/handlebars.js** and include it at the very top of **ownnotes/templates/main.php** before the other scripts and styles: +To create a modern webapp you need to write :doc:`JavaScript`. You can use any JavaScript framework but for this tutorial we want to keep it as simple as possible and therefore only include the templating library `handlebarsjs `_. `Download the file `_ into **ownnotes/js/handlebars.js** and include it at the very top of **ownnotes/templates/main.php** before the other scripts and styles: .. code-block:: php @@ -1048,9 +1048,9 @@ To create a modern webapp you need to write :doc:`JavaScript`. You can use a Creating a navigation --------------------- -The template file **ownnotes/templates/part.navigation.php** contains the navigation. Nextcloud defines many handy :doc:`CSS styles ` which we are going to reuse to style the navigation. Adjust the file to contain only the following code: +The template file **ownnotes/templates/part.navigation.php** contains the navigation. Nextcloud defines many handy :doc:`CSS styles ` which we are going to reuse to style the navigation. Adjust the file to contain only the following code: -.. note:: **$l->t()** is used to make your strings :doc:`translatable ` and **p()** is used :doc:`to print escaped HTML ` +.. note:: **$l->t()** is used to make your strings :doc:`translatable ` and **p()** is used :doc:`to print escaped HTML ` .. code-block:: php @@ -1312,7 +1312,7 @@ When the page is loaded we want all the existing notes to load. Furthermore we w Apply finishing touches ----------------------- -Now the only thing left is to style the textarea in a nicer fashion. To do that open **ownnotes/css/style.css** and replace the content with the following :doc:`CSS ` code: +Now the only thing left is to style the textarea in a nicer fashion. To do that open **ownnotes/css/style.css** and replace the content with the following :doc:`CSS ` code: .. code-block:: css diff --git a/developer_manual/app/view/templates.rst b/developer_manual/app/view/templates.rst index 29b319e61..c6ae0589e 100644 --- a/developer_manual/app/view/templates.rst +++ b/developer_manual/app/view/templates.rst @@ -4,7 +4,7 @@ Templates .. sectionauthor:: Bernhard Posselt -Nextcloud provides its own templating system which is basically plain PHP with some additional functions and preset variables. All the parameters which have been passed from the :doc:`controller ` are available in an array called **$_[]**, e.g.:: +Nextcloud provides its own templating system which is basically plain PHP with some additional functions and preset variables. All the parameters which have been passed from the :doc:`controller <../requests/controllers>` are available in an array called **$_[]**, e.g.:: array('key' => 'something') diff --git a/developer_manual/general/security.rst b/developer_manual/general/security.rst index 36b55d18c..6a5065f39 100644 --- a/developer_manual/general/security.rst +++ b/developer_manual/general/security.rst @@ -204,7 +204,7 @@ Nextcloud offers three simple checks: * **OCP\\JSON::checkAdminUser()**: Checks if the logged in user has admin privileges * **OCP\\JSON::checkSubAdminUser()**: Checks if the logged in user has group admin privileges -Using the App Framework, these checks are already automatically performed for each request and have to be explicitly turned off by using annotations above your controller method, see :doc:`../app/controllers`. +Using the App Framework, these checks are already automatically performed for each request and have to be explicitly turned off by using annotations above your controller method, see :doc:`../app/requests/controllers`. Additionally always check if the user has the right to perform that action. (e.g. a user should not be able to delete other users' bookmarks). @@ -227,7 +227,7 @@ To prevent CSRF in an app, be sure to call the following method at the top of al