Skip to content

Commit

Permalink
docs(Userguide): strip redundant tabs or replace with 4 spaces
Browse files Browse the repository at this point in the history
  • Loading branch information
@kilofox
kilofox committed Aug 4, 2023
1 parent 292f45f commit c28be3f
Show file tree
Hide file tree
Showing 5 changed files with 149 additions and 149 deletions.
58 changes: 29 additions & 29 deletions modules/userguide/guide/developers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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

Expand All @@ -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.
Expand Down
88 changes: 44 additions & 44 deletions modules/userguide/guide/userguide/adding.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,57 +4,57 @@ Making your module work with the User Guide is simple.

First, copy this config and place in it `<module>/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'
*/
'<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' => '<Module Name>',

// A short description of this module, shown on the index page
'description' => '<Description goes here>',

// Copyright message, shown in the footer for this module
'copyright' => '&copy; 2018 <Your Name>',
]
],
/*
* 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_<class_name> 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'
*/
'<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' => '<Module Name>',

// A short description of this module, shown on the index page
'description' => '<Description goes here>',

// Copyright message, shown in the footer for this module
'copyright' => '&copy; 2018 <Your Name>',
]
],
/*
* 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_<class_name> for your base classes
* then you would define:
*/
'transparent_prefixes' => [
'Modulename' => true,
]
];

Next, create a folder in your module directory called `guide/<modulename>` and create `index.md` and `menu.md`. The contents of `index.md` is what is shown on the index page of your module.

## Creating the side menu

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).

Expand Down
34 changes: 17 additions & 17 deletions modules/userguide/guide/userguide/config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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!
34 changes: 17 additions & 17 deletions modules/userguide/guide/userguide/contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <your name> git://github.com/<your name>/kohana.git
# Get the correct branch.
git checkout develop
# Add your repository as a new remote.
git remote add <your name> git://github.com/<your name>/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 <your name> 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 <your name> develop

4. Finally, send a pull request on GitHub.
Loading

0 comments on commit c28be3f

Please sign in to comment.