From acbba9adb2e362079ce1fb84be1868b198cc1da0 Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sat, 23 Oct 2021 13:43:24 +0200 Subject: Improved markdownlint (#3918) * Improved markdownlint * Relaxed rules slighlty * `npm run markdownlint` for automatic tests * `npm run markdownlint_fix` for automatic syntax fixing * Applied the fixes on all our Markdown files --- docs/en/developers/01_Index.md | 1 + docs/en/developers/02_First_steps.md | 4 +-- .../en/developers/03_Backend/01_Database_schema.md | 4 ++- .../03_Backend/04_Changing_source_code.md | 18 +++++++------ docs/en/developers/03_Backend/05_Extensions.md | 30 ++++++++++++---------- docs/en/developers/04_Frontend/01_View_files.md | 18 +++++++------ docs/en/developers/04_Frontend/02_Design.md | 12 ++++----- docs/en/developers/05_Release_new_version.md | 7 ++--- docs/en/developers/06_Fever_API.md | 20 +++++++-------- docs/en/developers/06_GoogleReader_API.md | 12 ++++----- docs/en/developers/06_Reporting_Bugs.md | 22 ++++++++-------- 11 files changed, 80 insertions(+), 68 deletions(-) (limited to 'docs/en/developers') diff --git a/docs/en/developers/01_Index.md b/docs/en/developers/01_Index.md index 94339f7cb..28d11a6cc 100644 --- a/docs/en/developers/01_Index.md +++ b/docs/en/developers/01_Index.md @@ -27,4 +27,5 @@ Start by creating your development environment. A guide to setting up FreshRSS's * [Design (Themes/Theming)](04_Frontend/02_Design.md) ## Minz + Minz is the homemade PHP framework used by FreshRSS. More information can be found [here](Minz/index.md). diff --git a/docs/en/developers/02_First_steps.md b/docs/en/developers/02_First_steps.md index 21456fea4..626ee84fc 100644 --- a/docs/en/developers/02_First_steps.md +++ b/docs/en/developers/02_First_steps.md @@ -208,7 +208,7 @@ Please ensure that your code works with the oldest PHP version officially suppor ## Miscellaneous -### Operators +### Operators on multiple lines Operators must be at the end of the line if a condition is split over more than one line. @@ -219,7 +219,7 @@ if ($a == 10 || } ``` -### End of file +### End of PHP file If the file contains only PHP code, the PHP closing tag must be omitted. diff --git a/docs/en/developers/03_Backend/01_Database_schema.md b/docs/en/developers/03_Backend/01_Database_schema.md index 1978eabea..b2206e46a 100644 --- a/docs/en/developers/03_Backend/01_Database_schema.md +++ b/docs/en/developers/03_Backend/01_Database_schema.md @@ -1 +1,3 @@ -# Database Schema \ No newline at end of file +# Database Schema + +> **TODO** diff --git a/docs/en/developers/03_Backend/04_Changing_source_code.md b/docs/en/developers/03_Backend/04_Changing_source_code.md index e8a5958e4..2f5ed8e14 100644 --- a/docs/en/developers/03_Backend/04_Changing_source_code.md +++ b/docs/en/developers/03_Backend/04_Changing_source_code.md @@ -1,15 +1,17 @@ -# Accessing the database +# Changing the source code -**TODO** +## Accessing the database -# Writing an action and its related view +> **TODO** -**TODO** +## Writing an action and its related view -# Authentication +> **TODO** -**TODO** +## Authentication -# Logs +> **TODO** -**TODO** \ No newline at end of file +## Logs + +> **TODO** diff --git a/docs/en/developers/03_Backend/05_Extensions.md b/docs/en/developers/03_Backend/05_Extensions.md index e5e2e51e6..81fd13ecb 100644 --- a/docs/en/developers/03_Backend/05_Extensions.md +++ b/docs/en/developers/03_Backend/05_Extensions.md @@ -38,7 +38,8 @@ Minz relies on and imposes an MVC architecture on projects using it. This archit ### Routing -In order to link a URL to a controller, first you have to go through a "routing" phase. In FreshRSS, this is particularly simple because it suffices to specify the name of the controller to load into the URL using a `c` parameter. For example, the address http://exemple.com?c=hello will execute the code contained in the `hello` controller. +In order to link a URL to a controller, first you have to go through a "routing" phase. In FreshRSS, this is particularly simple because it suffices to specify the name of the controller to load into the URL using a `c` parameter. +For example, the address will execute the code contained in the `hello` controller. One concept that has not yet been discussed is the "actions" system. An action is executed *on* a controller. Concretely, a controller is represented by a class and its actions by methods. To execute an action, it is necessary to specify an `a` parameter in the URL. @@ -60,9 +61,10 @@ class FreshRSS_hello_Controller extends Minz_ActionController { ?> ``` -When loading the address http://exemple.com?c=hello&a=world, the `world` action is executed on the `hello` controller. +When loading the address , the `world` action is executed on the `hello` controller. -Note: if `c` or `a` is not specified, the default value for each of these variables is `index`. So the address http://exemple.com?c=hello will execute the `index` action of the `hello` controller. +Note: if `c` or `a` is not specified, the default value for each of these variables is `index`. +So the address will execute the `index` action of the `hello` controller. From now on, the `hello/world` naming convention will be used to refer to a controller/action pair. @@ -123,7 +125,7 @@ To take full advantage of the Minz routing system, it is strongly discouraged to

``` -If one day it was decided to use a "url rewriting" system to have addresses in a http://exemple.com/controller/action format, all previous addresses would become ineffective! +If one day it was decided to use a "url rewriting" system to have addresses in a format, all previous addresses would become ineffective! So use the `Minz_Url` class and its `display()` method instead. `Minz_Url::display()` takes an array of the following form as its argument: @@ -219,7 +221,7 @@ An extension allows you to easily add functionality to FreshRSS without having t ### Make it work in Docker When working on an extension, it's easier to see it working directly in its environment. With Docker, you can leverage the use of the ```volume``` option when starting the container. Hopefully, you can use it without Docker-related knowledge by using the Makefile rule: -``` +```sh make start extensions="/full/path/to/extension/1 /full/path/to/extension/2" ``` @@ -239,13 +241,14 @@ but you should follow our best practice: If you want to write a `HelloWorld` extension, the directory name should be `xExtension-HelloWorld` and the base class name `HelloWorldExtension`. In the file `freshrss/extensions/xExtension-HelloWorld/extension.php` you need the structure: -```html +```php class HelloWorldExtension extends Minz_Extension { public function init() { // your code here } } ``` + There is an example HelloWorld extension that you can download from [our GitHub repo](https://github.com/FreshRSS/xExtension-HelloWorld). You may also need additional files or subdirectories depending on your needs: @@ -254,9 +257,9 @@ You may also need additional files or subdirectories depending on your needs: * A `static/` directory containing CSS and JavaScript files that you will need for your extension (note that if you need to write a lot of CSS it may be more interesting to write a complete theme) * A `Controllers` directory containing additional controllers * An `i18n` directory containing additional translations -* `layout` and` views` directories to define new views or to overwrite the current views +* `layout` and `views` directories to define new views or to overwrite the current views -In addition, it is good to have a `LICENSE` file indicating the license under which your extension is distributed and a` README` file giving a detailed description of it. +In addition, it is good to have a `LICENSE` file indicating the license under which your extension is distributed and a `README` file giving a detailed description of it. ### The metadata.json file @@ -266,10 +269,11 @@ The `metadata.json` file defines your extension through a number of important el * `author`: your name, your e-mail address ... but there is no specific format to adopt * `description`: a description of your extension * `version`: the current version number of the extension -* `entrypoint`: Indicates the entry point of your extension. It must match the name of the class contained in the file `extension.php` without the suffix` Extension` (so if the entry point is `HelloWorld`, your class will be called` HelloWorldExtension`) -* `type`: Defines the type of your extension. There are two types: `system` and` user`. We will study this difference right after. +* `entrypoint`: Indicates the entry point of your extension. It must match the name of the class contained in the file `extension.php` without the suffix `Extension` +(so if the entry point is `HelloWorld`, your class will be called `HelloWorldExtension`) +* `type`: Defines the type of your extension. There are two types: `system` and `user`. We will study this difference right after. -Only the `name` and` entrypoint` fields are required. +Only the `name` and `entrypoint` fields are required. ### Choosing between `system` and `user` @@ -296,7 +300,7 @@ The `Minz_Extension` abstract class defines a set of methods that can be overrid The `Minz_Extension` abstract class defines another set of methods that should not be overridden: * the `getName`, `getEntrypoint`, `getPath`, `getAuthor`, `getDescription`, `getVersion`, and `getType` methods return the extension internal properties. Those properties are extracted from the `metadata.json` file. * the `getFileUrl` returns the URL of the selected file. The file must exist in the `static` folder of the extension. -* the `registerController` method register an extension controller in FreshRSS. The selected controller must be defined in the extension _Controllers_ folder, its file name must be _Controller.php_, and its class name must be *FreshExtension\_\_Controller*. +* the `registerController` method register an extension controller in FreshRSS. The selected controller must be defined in the extension _Controllers_ folder, its file name must be _\Controller.php_, and its class name must be *FreshExtension_\_Controller*. * the `registerViews` method registers the extension views in FreshRSS. * the `registerTranslates` method registers the extension translation files in FreshRSS. * the `registerHook` method registers hook actions in different part of the application. @@ -348,4 +352,4 @@ The following events are available: When you want to support user configurations for your extension or simply display some information, you have to create the `configure.phtml` file. -**TODO** +> **TODO** diff --git a/docs/en/developers/04_Frontend/01_View_files.md b/docs/en/developers/04_Frontend/01_View_files.md index 5eb284dde..5a270b5ef 100644 --- a/docs/en/developers/04_Frontend/01_View_files.md +++ b/docs/en/developers/04_Frontend/01_View_files.md @@ -1,15 +1,17 @@ -# The .phtml files +# View files -**TODO** +## The .phtml files -# Writing a URL +> **TODO** -**TODO** +## Writing a URL -# Displaying an icon +> **TODO** -**TODO** +## Displaying an icon -# Internationalisation +> **TODO** -**TODO** +## Internationalisation + +> **TODO** diff --git a/docs/en/developers/04_Frontend/02_Design.md b/docs/en/developers/04_Frontend/02_Design.md index 74b92dee2..4ec8253ad 100644 --- a/docs/en/developers/04_Frontend/02_Design.md +++ b/docs/en/developers/04_Frontend/02_Design.md @@ -19,7 +19,7 @@ RTL (right-to-left) support for languages such as Hebrew and Arabic is handled t ## Overriding icons -To replace the default icons, add an "icons" folder to your theme's folder. Use files with the same name as the default icon to override them. +To replace the default icons, add an "icons" folder to your theme's folder. Use files with the same name as the default icon to override them. ## Template file @@ -27,11 +27,11 @@ To replace the default icons, add an "icons" folder to your theme's folder. Use ```json { - "name": "Theme name", - "author": "Theme author", - "description": "Theme description", - "version": 0.1, - "files": ["_template.css", "file1.css", "file2.css"] + "name": "Theme name", + "author": "Theme author", + "description": "Theme description", + "version": 0.1, + "files": ["_template.css", "file1.css", "file2.css"] } ``` diff --git a/docs/en/developers/05_Release_new_version.md b/docs/en/developers/05_Release_new_version.md index f4e38d0de..918451490 100644 --- a/docs/en/developers/05_Release_new_version.md +++ b/docs/en/developers/05_Release_new_version.md @@ -1,6 +1,7 @@ # Preparing the release -In order to get as much feedback as possible before a release, it's preferable to announce it on GitHub by creating a dedicated ticket ([see examples] (https://github.com/FreshRSS/FreshRSS/search?utf8=%E2%9C%93&q=Call+for+testing&type=Issues)). This should be done **at least one week in advance**. +In order to get as much feedback as possible before a release, it's preferable to announce it on GitHub by creating a dedicated ticket +([see examples](https://github.com/FreshRSS/FreshRSS/search?utf8=%E2%9C%93&q=Call+for+testing&type=Issues)). This should be done **at least one week in advance**. It's also recommended to make the announcement on mailing@freshrss.org. @@ -12,7 +13,7 @@ You must also **make sure that the CHANGELOG file is up to date** with the updat ## Git process -```sh +```console $ git checkout edge $ git pull $ vim constants.php @@ -98,7 +99,7 @@ When everything's working, it's time to announce the release to the world! ## Starting the next development version -```sh +```console $ git checkout edge $ vim constants.php # Update the FRESHRSS_VERSION diff --git a/docs/en/developers/06_Fever_API.md b/docs/en/developers/06_Fever_API.md index bcd9db660..909fd6074 100644 --- a/docs/en/developers/06_Fever_API.md +++ b/docs/en/developers/06_Fever_API.md @@ -50,7 +50,7 @@ The following features are not supported: If this API does not work as expected in your RSS reader, you can test it manually with a tool like [Postman](https://www.getpostman.com/). -Configure a POST request to the URL https://freshrss.example.net/api/fever.php?api which should give you the result: +Configure a POST request to the URL which should give you the result: ```json { "api_version": 3, @@ -84,15 +84,15 @@ Perfect, you're now authenticated and you can start testing the more advanced fe Some basic calls are: -* https://freshrss.example.net/api/fever.php?api&items -* https://freshrss.example.net/api/fever.php?api&feeds -* https://freshrss.example.net/api/fever.php?api&groups -* https://freshrss.example.net/api/fever.php?api&unread_item_ids -* https://freshrss.example.net/api/fever.php?api&saved_item_ids -* https://freshrss.example.net/api/fever.php?api&items&since_id=some_id -* https://freshrss.example.net/api/fever.php?api&items&max_id=some_id -* https://freshrss.example.net/api/fever.php?api&mark=item&as=read&id=some_id -* https://freshrss.example.net/api/fever.php?api&mark=item&as=unread&id=some_id +* +* +* +* +* +* +* +* +* Replace `some_id` with a real ID from your `freshrss_username_entry` database. diff --git a/docs/en/developers/06_GoogleReader_API.md b/docs/en/developers/06_GoogleReader_API.md index 823b4c8b0..5035ca6cf 100644 --- a/docs/en/developers/06_GoogleReader_API.md +++ b/docs/en/developers/06_GoogleReader_API.md @@ -5,21 +5,21 @@ Additionally [page about our Fever compatible API](06_Fever_API.md) for another ## RSS clients -There are many RSS clients that support the Fever API, but they seem to understand the Fever API a bit differently. +There are many RSS clients that support the Fever API, but they might understand the API a bit differently. If your favourite client doesn't work properly with this API, please create an issue and we'll have a look. But we can **only** do that for free clients. -### Usage & Authentication +## Usage & Authentication Before you can start using this API, you have to enable and setup API access, which is [documented here](../users/06_Mobile_access.md), and then reset the user’s API password. Then point your mobile application to the `greader.php` address (e.g. `https://freshrss.example.net/api/greader.php`). -# Compatible clients +## Compatible clients -6. On the same FreshRSS API page, note the address given under “Your API address”, like `https://freshrss.example.net/api/greader.php` - * Type the API address in a client, together with your FreshRSS username, and the corresponding special API password. +1. On the same FreshRSS API page, note the address given under “Your API address”, like `https://freshrss.example.net/api/greader.php` +2. Type the API address in a client, together with your FreshRSS username, and the corresponding special API password. | App | Platform | License | |:----------------------------------------------------------------------------------:|:-------------------:|:--------------------------------------------------------:| @@ -34,7 +34,7 @@ Then point your mobile application to the `greader.php` address (e.g. `https://f |[Reeder](https://www.reederapp.com/) |MacOS, iOS |Closed Source | |[FreshRSS-Notify](https://addons.mozilla.org/firefox/addon/freshrss-notify-webextension/) |Firefox |Open Source | -# Google Reader compatible API +## Google Reader compatible API Examples of basic queries: diff --git a/docs/en/developers/06_Reporting_Bugs.md b/docs/en/developers/06_Reporting_Bugs.md index 12d3259a6..77b16251f 100644 --- a/docs/en/developers/06_Reporting_Bugs.md +++ b/docs/en/developers/06_Reporting_Bugs.md @@ -8,12 +8,12 @@ If you're convinced that you should be heard, here's how you can go about it. GitHub is the ideal platform to submit your requests. It allows us to discuss a problem or suggestion with others and it often generates new ideas. Let's not neglect this "social" aspect! - 1. [Go to the bug ticket manager](https://github.com/FreshRSS/FreshRSS/issues) - 2. Start by checking if a similar request hasn't already been made. If so, please feel free to add your voice to the request. - 3. If your request is new, [open a new bug ticket](https://github.com/FreshRSS/FreshRSS/issues/new) - 4. Finally, write your request. If you're fluent in English, it's the preferred language because it allows for discussion with the largest number of people. - 5. Please follow the tips below to make it easier to let your ticket be heard. - +1. [Go to the bug ticket manager](https://github.com/FreshRSS/FreshRSS/issues) +2. Start by checking if a similar request hasn't already been made. If so, please feel free to add your voice to the request. +3. If your request is new, [open a new bug ticket](https://github.com/FreshRSS/FreshRSS/issues/new) +4. Finally, write your request. If you're fluent in English, it's the preferred language because it allows for discussion with the largest number of people. +5. Please follow the tips below to make it easier to let your ticket be heard. + ## Informal Not everyone likes or uses GitHub for a variety of legitimate reasons. That is why you can also contact us in a more informal way. @@ -59,8 +59,8 @@ So that we understand what you consider to be the problem. Remember to give the following information if you know it: - 1. Which browser? Which version? - 2. Which server: Apache, Nginx? Which version? - 3. Which version of PHP? - 4. Which database: SQLite, MySQL, MariaDB, PostgreSQL? Which version? - 5. Which distribution runs on the server? And... which version? +1. Which browser? Which version? +2. Which server: Apache, Nginx? Which version? +3. Which version of PHP? +4. Which database: SQLite, MySQL, MariaDB, PostgreSQL? Which version? +5. Which distribution runs on the server? And... which version? -- cgit v1.2.3