From c28be3f5fc01f3caa605aa905d269cc0613a1910 Mon Sep 17 00:00:00 2001 From: Tinsh Date: Sat, 5 Aug 2023 00:08:19 +0800 Subject: [PATCH] docs(Userguide): strip redundant tabs or replace with 4 spaces --- modules/userguide/guide/developers.md | 58 ++++++------ modules/userguide/guide/userguide/adding.md | 88 +++++++++---------- modules/userguide/guide/userguide/config.md | 34 +++---- .../userguide/guide/userguide/contributing.md | 34 +++---- modules/userguide/guide/userguide/markdown.md | 84 +++++++++--------- 5 files changed, 149 insertions(+), 149 deletions(-) diff --git a/modules/userguide/guide/developers.md b/modules/userguide/guide/developers.md index c0e0323..668b76a 100644 --- a/modules/userguide/guide/developers.md +++ b/modules/userguide/guide/developers.md @@ -32,27 +32,27 @@ Release branch names follow the same convention in both kohana/kohana and kohana To work on 3.0.x you'd do the following: - > git clone git://github.com/kohana/kohana.git - .... - - > cd kohana - > git submodule update --init - .... + > git clone git://github.com/kohana/kohana.git + .... - > git checkout 3.0.x - Switched to branch '3.0.x' - > git submodule update + > cd kohana + > git submodule update --init + .... - > cd system - > git checkout 3.0.x - # Switched to branch 3.0.x + > git checkout 3.0.x + Switched to branch '3.0.x' + > git submodule update + + > cd system + > git checkout 3.0.x + # Switched to branch 3.0.x It's important that you follow the last step, because unlike svn, git submodules point at a specific commit rather than the tip of a branch. If you cd into the system folder after a `git submodule update` and run `git status` you'll be told: - # Not currently on any branch. - nothing to commit (working directory clean) + # Not currently on any branch. + nothing to commit (working directory clean) Similarly, if you want to work on modules, make sure you checkout the correct branch before you start working. @@ -66,33 +66,33 @@ until they're stable and **tests have been written for the feature**. The naming convention for feature branches is: - feature/{issue number}-{short hyphenated description} - - // i.e. + feature/{issue number}-{short hyphenated description} + + // i.e. + + feature/4045-rewriting-config-system - feature/4045-rewriting-config-system - When a new feature is complete and tested it can be merged into its respective release branch using `git pull --no-ff`. The `--no-ff` switch is important as it tells git to always create a commit detailing what branch you're merging from. This makes it a lot easier to analyse a feature's history. Here's a quick example: - > git status - # On branch feature/4045-rewriting-everything - - > git checkout 3.1.x - # Switched to branch '3.1.x' + > git status + # On branch feature/4045-rewriting-everything + + > git checkout 3.1.x + # Switched to branch '3.1.x' - > git merge --no-ff feature/4045-rewriting-everything + > git merge --no-ff feature/4045-rewriting-everything **If a change you make intentionally breaks the api then please correct the relevant tests before pushing!** -### Bug fixing +### Bug fixing If you're making a bugfix then before you start create a unit test which reproduces the bug, using the `@ticket` notation in the test to reference the bug's issue number -(i.e. `@ticket 4045` for issue #4045). +(i.e. `@ticket 4045` for issue #4045). If you run the test then the one you've just made should fail. @@ -125,7 +125,7 @@ section [in the git-scm book](http://book.git-scm.com/3_basic_branching_and_merg The simplest way to fix this is to remove all the changes that you've made locally. -You can do this using +You can do this using > git reset --hard kohana @@ -142,7 +142,7 @@ Then find the hash of the offending local commit and run: i.e. - > git rebase -i 57d0b28 + > git rebase -i 57d0b28 A text editor will open with a list of commits, delete the line containing the offending commit before saving the file & closing your editor. diff --git a/modules/userguide/guide/userguide/adding.md b/modules/userguide/guide/userguide/adding.md index a618467..f781541 100644 --- a/modules/userguide/guide/userguide/adding.md +++ b/modules/userguide/guide/userguide/adding.md @@ -4,42 +4,42 @@ Making your module work with the User Guide is simple. First, copy this config and place in it `/config/userguide.php`, replacing anything in `<>` with the appropriate values: - return [ - // Leave this alone - 'modules' => [ - /* - * The path to this module's userguide pages, without the 'guide/'. - * - * For example, '/guide/modulename/' would be 'modulename' - */ - '' => [ - // Whether this module's user guide pages should be shown - 'enabled' => true, - - // The name that should show up on the user guide index page - 'name' => '', - - // A short description of this module, shown on the index page - 'description' => '', - - // Copyright message, shown in the footer for this module - 'copyright' => '© 2018 ', - ] - ], - /* - * If you use transparent extensions outside the Kohana_ namespace, - * add your class prefix here. Both common Kohana naming conventions are - * excluded: - * - Modulename extends Modulename_Core - * - Foo extends Modulename_Foo - * - * For example, if you use Modulename_ for your base classes - * then you would define: - */ - 'transparent_prefixes' => [ - 'Modulename' => true, - ] - ]; + return [ + // Leave this alone + 'modules' => [ + /* + * The path to this module's userguide pages, without the 'guide/'. + * + * For example, '/guide/modulename/' would be 'modulename' + */ + '' => [ + // Whether this module's user guide pages should be shown + 'enabled' => true, + + // The name that should show up on the user guide index page + 'name' => '', + + // A short description of this module, shown on the index page + 'description' => '', + + // Copyright message, shown in the footer for this module + 'copyright' => '© 2018 ', + ] + ], + /* + * If you use transparent extensions outside the Kohana_ namespace, + * add your class prefix here. Both common Kohana naming conventions are + * excluded: + * - Modulename extends Modulename_Core + * - Foo extends Modulename_Foo + * + * For example, if you use Modulename_ for your base classes + * then you would define: + */ + 'transparent_prefixes' => [ + 'Modulename' => true, + ] + ]; Next, create a folder in your module directory called `guide/` and create `index.md` and `menu.md`. The contents of `index.md` is what is shown on the index page of your module. @@ -47,14 +47,14 @@ Next, create a folder in your module directory called `guide/` and c The contents of the `menu.md` file is what shows up in the side column and should be formatted like this: - ## [Module Name]() - - [Page name](page-path) - - [This is a Category](category) - - [Sub Page](category/sub-page) - - [Another](category/another) - - [Sub sub page](category/another/sub-page) - - Categories do not have to be a link to a page - - [Etcetera](etc) + ## [Module Name]() + - [Page name](page-path) + - [This is a Category](category) + - [Sub Page](category/sub-page) + - [Another](category/another) + - [Sub sub page](category/another/sub-page) + - Categories do not have to be a link to a page + - [Etcetera](etc) You can have items that are not linked pages (a category that doesn't have a corresponding page). diff --git a/modules/userguide/guide/userguide/config.md b/modules/userguide/guide/userguide/config.md index e07e0b4..7e16489 100644 --- a/modules/userguide/guide/userguide/config.md +++ b/modules/userguide/guide/userguide/config.md @@ -2,25 +2,25 @@ The userguide has the following config options, available in `config/userguide.php`. - return [ - // Enable the API browser. true or false - 'api_browser' => true, - // Enable these packages in the API browser. true for all packages, or a string of comma seperated packages, using 'None' for a class with no @package - // Example: 'api_packages' => 'Kohana,Kohana/Database,Kohana/ORM,None', - 'api_packages' => true, - ]; + return [ + // Enable the API browser. true or false + 'api_browser' => true, + // Enable these packages in the API browser. true for all packages, or a string of comma seperated packages, using 'None' for a class with no @package + // Example: 'api_packages' => 'Kohana,Kohana/Database,Kohana/ORM,None', + 'api_packages' => true, + ]; You can enable or disable the entire API browser, or limit it to only show certain packages. To disable a module from showing pages in the userguide, simply change that module's `enabled` option within the `application/config/userguide.php` file. For example: - return [ - 'modules' => [ - 'kohana' => [ - 'enabled' => false, - ], - 'database' => [ - 'enabled' => false, - ] - ] - ] + return [ + 'modules' => [ + 'kohana' => [ + 'enabled' => false, + ], + 'database' => [ + 'enabled' => false, + ] + ] + ] Using this you could make the userguide only show your modules and classes in the API browser, if you wanted to host your own documentation on your site. Feel free to change the styles and views as well, but be sure to give credit where credit is due! \ No newline at end of file diff --git a/modules/userguide/guide/userguide/contributing.md b/modules/userguide/guide/userguide/contributing.md index 9cac017..72eb655 100644 --- a/modules/userguide/guide/userguide/contributing.md +++ b/modules/userguide/guide/userguide/contributing.md @@ -36,26 +36,26 @@ Once your pull request has been accepted, you can delete your repository if you 2. Now you need to add your fork as a "git remote" to your application and ensure you are on the right branch. - cd my-kohana-app + cd my-kohana-app - # Add your repository as a new remote. - git remote add git://github.com//kohana.git - - # Get the correct branch. - git checkout develop + # Add your repository as a new remote. + git remote add git://github.com//kohana.git + + # Get the correct branch. + git checkout develop 3. Now go into the repo of the area of docs you want to contribute to and add your forked repo as a new remote, and push to it. - # Make some changes to the docs. - nano file.md - - # Commit your changes - Use a descriptive commit message! If there is a redmine ticket for the changes you are making include "Fixes #XXXXX" in the commit message so its tracked. - git commit -a -m "Corrected a typo in the ORM docs. Fixes #12345." - - # Make sure we are up to date with the latest changes. - git merge origin/develop - - # Now push your changes to your fork. - git push develop + # Make some changes to the docs. + nano file.md + + # Commit your changes - Use a descriptive commit message! If there is a redmine ticket for the changes you are making include "Fixes #XXXXX" in the commit message so its tracked. + git commit -a -m "Corrected a typo in the ORM docs. Fixes #12345." + + # Make sure we are up to date with the latest changes. + git merge origin/develop + + # Now push your changes to your fork. + git push develop 4. Finally, send a pull request on GitHub. diff --git a/modules/userguide/guide/userguide/markdown.md b/modules/userguide/guide/userguide/markdown.md index a19eed8..2fb1f26 100644 --- a/modules/userguide/guide/userguide/markdown.md +++ b/modules/userguide/guide/userguide/markdown.md @@ -7,12 +7,12 @@ The userguide uses [Markdown](http://daringfireball.net/projects/markdown/) and ## Headers # Header 1 - - ## Header 2 - - ### Header 3 - - #### Header 4 + + ## Header 2 + + ### Header 3 + + #### Header 4 ## Paragraphs ~~~ @@ -52,24 +52,24 @@ This link has a title: [Kohana](http://kohanaframework.org "The swift PHP framew ## Code blocks - For inline code simply surround some `text with tick marks.` - + For inline code simply surround some `text with tick marks.` + For inline code simply surround some `text with tick marks.` - // For a block of code, - // indent in four spaces, - // or with a tab + // For a block of code, + // indent in four spaces, + // or with a tab You can also do a "fenced" code block: - ~~~ - A fenced code block has tildes - above and below it - This is sometimes useful when code is near lists - ~~~ + ~~~ + A fenced code block has tildes + above and below it + This is sometimes useful when code is near lists + ~~~ ~~~ A fenced code block has tildes - above and below it + above and below it This is sometimes useful when code is near lists ~~~ @@ -101,17 +101,17 @@ This is sometimes useful when code is near lists ~~~ * To nest lists you just add four spaces before the * or number - 1. Like this - * It's pretty basic, this line has eight spaces, so its nested twice - 1. And this line is back to the second level - * Out to third level again + 1. Like this + * It's pretty basic, this line has eight spaces, so its nested twice + 1. And this line is back to the second level + * Out to third level again * And back to the first level ~~~ * To nest lists you just add four spaces before the * or number - 1. Like this - * It's pretty basic, this line has eight spaces, so its nested twice - 1. And this line is back to the second level - * Out to third level again + 1. Like this + * It's pretty basic, this line has eight spaces, so its nested twice + 1. And this line is back to the second level + * Out to third level again * And back to the first level ## Italics and Bold @@ -145,9 +145,9 @@ _____________________ Image syntax looks like this: - ![Alt text](/path/to/img.jpg) - - ![Alt text](/path/to/img.jpg "Optional title") + ![Alt text](/path/to/img.jpg) + + ![Alt text](/path/to/img.jpg "Optional title") [!!] Note that the images in userguide are [namespaced](#namespacing). @@ -198,40 +198,40 @@ To link to page in a different module, prefix your url with `../` and the module You can make links to the api browser by wrapping any class name in brackets. You may also include a function name, or propery name to link to that specifically. All of the following will link to the API browser: - [Request] - [Request::execute] - [Request::execute()] - [Request::$status] + [Request] + [Request::execute] + [Request::execute()] + [Request::$status] -[Request] -[Request::execute] -[Request::execute()] -[Request::$status] +[Request] +[Request::execute] +[Request::execute()] +[Request::$status] If you want to have parameters and have the function be clickable, only put the brackets around the class and function (not the params), and put a backslash in front of the opening parenthesis. - [Kohana::$config]\('foobar','baz') - + [Kohana::$config]\('foobar','baz') + [Kohana::$config]\('foobar','baz') ## Notes If you put `[!!]` in front of a line it will be a "note" and be placed in a box with a lightbulb. - [!!] This is a note + [!!] This is a note will display as: - + [!!] This is a note ## Headers automatically get IDs Headers are automatically assigned an id, based on the content of the header, so each header can be linked to. You can manually assign a different id using the syntax as defined in Markdown Extra. If multiple headers have the same content (e.g. more than one "Examples" header), only the first will get be automatically assigned an id, so you should manually assign more descriptive ids. For example: - ### Examples {#more-descriptive-id} + ### Examples {#more-descriptive-id} ## Including Views If you need you may include a regular Kohana View file by placing the name of the view in double curly brackets. **If the view is not found, no error or exception will be shown, the curly brackets and view name will simply remain there!** - {{some/view/file}} + {{some/view/file}}