diff --git a/.github/carson.yml b/.github/carson.yml index 07c841b7a021..deb4501859b9 100644 --- a/.github/carson.yml +++ b/.github/carson.yml @@ -22,7 +22,7 @@ settings: files: ['.github/workflows/*'] - label: documentation files: - all: ['user_guide_src/source/**'] + all: ['docs/**'] - label: testing files: all: ['tests/**'] diff --git a/.github/dependabot.yml b/.github/dependabot.yml index c6188a21b9e6..e511627ae3bc 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -24,3 +24,12 @@ updates: patterns: - '*' group-by: dependency-name + + - package-ecosystem: 'pip' + directory: '/docs' + schedule: + interval: 'weekly' + groups: + user-guide-dependencies: + patterns: + - '*' diff --git a/.github/instructions/user-guide.instructions.md b/.github/instructions/user-guide.instructions.md index 9b55a50ba3f1..c5eafc5a3999 100644 --- a/.github/instructions/user-guide.instructions.md +++ b/.github/instructions/user-guide.instructions.md @@ -1,11 +1,15 @@ --- -applyTo: "user_guide_src/**/*.rst" +applyTo: "docs/**/*.md" --- # User guide -- Preserve the existing reStructuredText structure, terminology, directives, +- Preserve the existing Markdown structure, terminology, admonitions, anchors, and surrounding writing style. +- Indent nested lists and admonition bodies by four spaces, and keep the two + trailing spaces that end a line as a hard line break. +- Add a new page to the page's folder `index.md` and run + `php admin/update-docs-nav.php` to add it to `docs/.nav.yml`. - Keep PHP examples compatible with PHP 8.2 and verify signatures and behavior against the current framework code. - Distinguish new behavior from existing behavior and document defaults @@ -22,6 +26,6 @@ applyTo: "user_guide_src/**/*.rst" smallest migration in both the minor changelog and upgrading guide. - Keep code examples minimal but complete enough to run in a normal CodeIgniter application. -- Leave the complete Sphinx build and documentation validation to GitHub +- Leave the complete MkDocs build and documentation validation to GitHub Actions unless the task specifically requires local documentation validation. diff --git a/.github/instructions/worker-mode.instructions.md b/.github/instructions/worker-mode.instructions.md index ec6e1742ec5a..ab0329da5983 100644 --- a/.github/instructions/worker-mode.instructions.md +++ b/.github/instructions/worker-mode.instructions.md @@ -1,5 +1,5 @@ --- -applyTo: "system/Boot.php,system/CodeIgniter.php,system/Commands/Worker/**,system/Config/BaseService.php,system/Config/Factories.php,system/Config/Factory.php,system/Config/Services.php,system/Database/Config.php,system/Database/BaseConnection.php,system/Database/ConnectionInterface.php,system/Database/*/Connection.php,system/Events/Events.php,system/Session/**,system/Cache/**,system/HTTP/**,system/Filters/**,system/Router/**,system/Security/**,system/Debug/Toolbar.php,system/Debug/Toolbar/**,app/Config/WorkerMode.php,tests/system/Commands/Worker/**,user_guide_src/source/installation/worker_mode.rst" +applyTo: "system/Boot.php,system/CodeIgniter.php,system/Commands/Worker/**,system/Config/BaseService.php,system/Config/Factories.php,system/Config/Factory.php,system/Config/Services.php,system/Database/Config.php,system/Database/BaseConnection.php,system/Database/ConnectionInterface.php,system/Database/*/Connection.php,system/Events/Events.php,system/Session/**,system/Cache/**,system/HTTP/**,system/Filters/**,system/Router/**,system/Security/**,system/Debug/Toolbar.php,system/Debug/Toolbar/**,app/Config/WorkerMode.php,tests/system/Commands/Worker/**,docs/installation/worker_mode.md" --- # FrankenPHP Worker Mode diff --git a/.github/skills/forum-announcement/SKILL.md b/.github/skills/forum-announcement/SKILL.md index e9e7c731a1a3..1a53513c9917 100644 --- a/.github/skills/forum-announcement/SKILL.md +++ b/.github/skills/forum-announcement/SKILL.md @@ -25,7 +25,7 @@ Create a forum-ready CodeIgniter4 release announcement using myBB markup. ## Procedure 1. Read `CHANGELOG.md` for release summary and PR references. -2. Read `user_guide_src/source/changelogs/v{VERSION}.rst` for each target version. +2. Read `docs/changelogs/v{VERSION}.md` for each target version. 3. Determine release mode: - Single release: one `4.x.y` version. - Dual release: maintenance + major; maintenance is presented first in the post. diff --git a/.gitignore b/.gitignore index 418eb60af297..ea4db348cfb5 100644 --- a/.gitignore +++ b/.gitignore @@ -42,11 +42,18 @@ $RECYCLE.BIN/ # These should never be under version control, # as it poses a security risk. .env -.vagrant -Vagrantfile -/user_guide_src/venv/ + +#------------------------- +# Local Configuration +#------------------------- +# phpenv local config +.php-version + +# pyenv local config .python-version -/user_guide_src/.python-version + +/phpunit.xml +/.php-cs-fixer.php #------------------------- # Temporary Files @@ -72,21 +79,19 @@ Vagrantfile php_errors.log #------------------------- -# User Guide Temp Files +# Build Output #------------------------- -/user_guide_src/build/* +# Test coverage +/build/ + +# phpDocumentor +/api/ + +# User guide /site/ /venv/ __pycache__/ -#------------------------- -# Test Files -#------------------------- -/tests/coverage* - -# Don't save phpunit under version control. -/phpunit - #------------------------- # Composer #------------------------- @@ -97,21 +102,13 @@ composer.lock # IDE / Development Files #------------------------- -# Modules Testing -_modules/* - -# phpenv local config -.php-version - # Jetbrains editors (PHPStorm, etc) .idea/ *.iml # Netbeans /nbproject/ -/build/ /nbbuild/ -/dist/ /nbdist/ /nbactions.xml /nb-configuration.xml @@ -124,12 +121,6 @@ _modules/* *.sublime-workspace *.sublime-project .phpintel -/api/ # Visual Studio Code .vscode/ - -/results/ -/phpunit.xml - -/.php-cs-fixer.php diff --git a/README.md b/README.md index 6a4e1025a8f5..8557b8d2a00d 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ More information about the plans for version 4 can be found in [CodeIgniter 4](h The [User Guide](https://codeigniter.com/user_guide/) is the primary documentation for CodeIgniter 4. -You will also find the [current **in-progress** User Guide](https://codeigniter4.github.io/CodeIgniter4/). +You will also find the [current **in-progress** User Guide](https://codeigniter4.github.io/CodeIgniter4/develop/). As with the rest of the framework, it is a work in progress, and will see changes over time to structure, explanations, etc. You might also be interested in the [API documentation](https://codeigniter4.github.io/api/) for the framework components. diff --git a/admin/framework/.gitignore b/admin/framework/.gitignore index 56b9f10d9160..0599343e84c3 100644 --- a/admin/framework/.gitignore +++ b/admin/framework/.gitignore @@ -42,8 +42,14 @@ $RECYCLE.BIN/ # These should never be under version control, # as it poses a security risk. .env -.vagrant -Vagrantfile + +#------------------------- +# Local Configuration +#------------------------- +# phpenv local config +.php-version + +/phpunit.xml #------------------------- # Temporary Files @@ -66,20 +72,13 @@ Vagrantfile php_errors.log #------------------------- -# User Guide Temp Files -#------------------------- -/user_guide_src/build/* -/user_guide_src/cilexer/build/* -/user_guide_src/cilexer/dist/* -/user_guide_src/cilexer/pycilexer.egg-info/* - -#------------------------- -# Test Files +# Build Output #------------------------- -/tests/coverage* +# Test coverage +/build/ -# Don't save phpunit under version control. -/phpunit +# phpDocumentor +/api/ #------------------------- # Composer @@ -90,21 +89,13 @@ vendor/ # IDE / Development Files #------------------------- -# Modules Testing -_modules/* - -# phpenv local config -.php-version - # Jetbrains editors (PHPStorm, etc) .idea/ *.iml # NetBeans /nbproject/ -/build/ /nbbuild/ -/dist/ /nbdist/ /nbactions.xml /nb-configuration.xml @@ -117,10 +108,6 @@ _modules/* *.sublime-workspace *.sublime-project .phpintel -/api/ # Visual Studio Code .vscode/ - -/results/ -/phpunit.xml diff --git a/admin/starter/.gitignore b/admin/starter/.gitignore index 56b9f10d9160..0599343e84c3 100644 --- a/admin/starter/.gitignore +++ b/admin/starter/.gitignore @@ -42,8 +42,14 @@ $RECYCLE.BIN/ # These should never be under version control, # as it poses a security risk. .env -.vagrant -Vagrantfile + +#------------------------- +# Local Configuration +#------------------------- +# phpenv local config +.php-version + +/phpunit.xml #------------------------- # Temporary Files @@ -66,20 +72,13 @@ Vagrantfile php_errors.log #------------------------- -# User Guide Temp Files -#------------------------- -/user_guide_src/build/* -/user_guide_src/cilexer/build/* -/user_guide_src/cilexer/dist/* -/user_guide_src/cilexer/pycilexer.egg-info/* - -#------------------------- -# Test Files +# Build Output #------------------------- -/tests/coverage* +# Test coverage +/build/ -# Don't save phpunit under version control. -/phpunit +# phpDocumentor +/api/ #------------------------- # Composer @@ -90,21 +89,13 @@ vendor/ # IDE / Development Files #------------------------- -# Modules Testing -_modules/* - -# phpenv local config -.php-version - # Jetbrains editors (PHPStorm, etc) .idea/ *.iml # NetBeans /nbproject/ -/build/ /nbbuild/ -/dist/ /nbdist/ /nbactions.xml /nb-configuration.xml @@ -117,10 +108,6 @@ _modules/* *.sublime-workspace *.sublime-project .phpintel -/api/ # Visual Studio Code .vscode/ - -/results/ -/phpunit.xml diff --git a/admin/userguide/.gitignore b/admin/userguide/.gitignore index d0eba7f4bdaa..41fc132dc574 100644 --- a/admin/userguide/.gitignore +++ b/admin/userguide/.gitignore @@ -5,9 +5,4 @@ !*/cache/index.html !*/cache/.htaccess -user_guide_src/build/* -user_guide_src/cilexer/build/* -user_guide_src/cilexer/dist/* -user_guide_src/cilexer/pycilexer.egg-info/* - /vendor/ diff --git a/contributing/ELDocs.tmbundle.zip b/contributing/ELDocs.tmbundle.zip deleted file mode 100644 index f7a11b364ca9..000000000000 Binary files a/contributing/ELDocs.tmbundle.zip and /dev/null differ diff --git a/contributing/documentation.md b/contributing/documentation.md new file mode 100644 index 000000000000..ae0231411a7b --- /dev/null +++ b/contributing/documentation.md @@ -0,0 +1,183 @@ +# Writing CodeIgniter Documentation + +CodeIgniter's user guide is written in Markdown, in the **docs/** folder, and built with [MkDocs](https://www.mkdocs.org/) and the [Material](https://squidfunnel.github.io/mkdocs-material/) theme. +The focus is on readability and user friendliness. +While the pages can be quite technical, we always write for humans! + +- [Tools Required](#tools-required) +- [Pages and the Navigation](#pages-and-the-navigation) +- [Page and Section Headings](#page-and-section-headings) +- [Links](#links) +- [Admonitions](#admonitions) +- [Text Decoration](#text-decoration) +- [Code Blocks](#code-blocks) +- [Line Breaks and Whitespace](#line-breaks-and-whitespace) + +## Tools Required + +To preview the rendered site, you need Python 3.11 or newer. Install MkDocs and its dependencies into a virtual environment: + +```console +python3 -m venv venv +venv/bin/pip install -r docs/requirements.txt +``` + +Then serve the user guide at , which reloads when you save a page: + +```console +venv/bin/mkdocs serve +``` + +GitHub Actions builds the user guide for every pull request that changes **docs/**, with `mkdocs build --strict`. +A broken link, a missing page or an unknown anchor fails the build, so you can leave the full validation to it unless you are changing the build itself. + +## Pages and the Navigation + +Each page is a Markdown file in **docs/**, such as **docs/libraries/pagination.md**. +The navigation is the file **docs/.nav.yml**. + +When you add a page, run the script that adds it to the navigation: + +```console +php admin/update-docs-nav.php +``` + +The script places the page in the section of its folder, in the order of the links in that folder's **index.md**. +Add the link to the **index.md** first, and edit **docs/.nav.yml** by hand only to change the order or the title of an entry. +The pull request check runs `php admin/update-docs-nav.php --check`, which fails when a page is missing from the navigation or an entry has no file. + +## Page and Section Headings + +Headings provide the order and the sections of a page, and they build the table of contents on the right of the page. +Use one `#` heading for the page title, then `##` for sections and `###` for subsections, without skipping a level: + +```markdown +# Page Title + +## Major Section + +### Subsection + +#### SubSubSection +``` + +Do not add a table of contents yourself. The theme builds it from the headings, down to the third level. + +## Links + +### To a Section + +Every heading gets an anchor from its text, in lowercase with hyphens in place of spaces and punctuation. +The heading `## Result Rows` has the anchor `#result-rows`. + +To link to a section of another page: + +```markdown +See [Result Rows](../database/results.md#result-rows) for how to read them. +``` + +To link to a section of the same page: + +```markdown +See [Result Rows](#result-rows) +``` + +### To a Page + +Link to the Markdown file with a path relative to the current page: + +```markdown +See the [Session](../libraries/sessions.md) library +``` + +### To a URL + +```markdown +[CodeIgniter 4 framework](https://github.com/codeigniter4/framework) +``` + +### To a Function or a Method + +Write the name as code, or link it to the page that describes it: + +```markdown +See [dot_array_search()](../helpers/array_helper.md) + +See `CodeIgniter\HTTP\Response::setCookie()` +``` + +## Admonitions + +Use an admonition for a note, a warning or a version badge. +The body is indented by four spaces. + +```markdown +!!! note "Note" + You must call this method first to generate correct pagination links. + +!!! important "Important" + Do not edit the files in the **system** folder. + +!!! warning "Warning" + This setting disables the CSRF protection. +``` + +The types in use are `note`, `important`, `warning`, `danger`, `success` and `tip`. + +### New Feature + +Mark a feature that is new in a version with a `success` admonition that has the title `Available from version`, followed by the version: + +```markdown +!!! success "Available from version 4.3.0" +``` + +### Deprecated + +Mark a deprecation with a `danger` admonition, and say what to use instead: + +```markdown +!!! danger "Deprecated since version 4.3.0" + Use `CodeIgniter\Database\BaseBuilder::setData()` instead. +``` + +## Text Decoration + +As a general rule, we use `**` for in-line file paths, and a single backtick for source code. + +E.g.: + +```markdown +Open the **app/Config/Filters.php** file and update the `$methods` property like the following: +``` + +## Code Blocks + +Fence a code block with three backticks and the name of its language. +PHP samples have no opening tag, and the highlighter expects that: + +````markdown +```php +$pager = service('pager'); +``` +```` + +### CLI Command + +Use the `console` language for a command that is run in a terminal: + +````markdown +```console +php spark migrate +``` +```` + +Other languages in use are `html`, `apache`, `json` and `text`. + +## Line Breaks and Whitespace + +Python-Markdown, the parser behind MkDocs, is stricter than the Markdown on GitHub: + +- Indent nested lists and the body of an admonition by four spaces. +- A line that ends with two spaces is a hard line break. Your editor must not trim them, and **.editorconfig** already turns trimming off for **docs/**. +- Leave a blank line before a list, a code fence and a table. diff --git a/contributing/documentation.rst b/contributing/documentation.rst deleted file mode 100644 index deedc29ebfc9..000000000000 --- a/contributing/documentation.rst +++ /dev/null @@ -1,186 +0,0 @@ -################################# -Writing CodeIgniter Documentation -################################# - -CodeIgniter uses Sphinx to generate its documentation in a variety of formats, -using `reStructuredText`_ to handle the formatting. If you are familiar with -Markdown or Textile, you will quickly grasp reStructuredText. The focus is -on readability and user friendliness. -While they can be quite technical, we always write for humans! - -.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html - -.. contents:: - :local: - -************** -Tools Required -************** - -To see the rendered HTML, ePub, PDF, etc., you will need to install Sphinx -along with the PHP domain extension for Sphinx. The underlying requirement -is to have Python installed. - -You can read more about installing all tools in **user_guide_src/README.rst** - -***************** -Table of Contents -***************** - -A local table of contents should always be included, like the one below. -It is created automatically by inserting the following:: - - .. contents:: - :local: - :depth: 2 - -***************************************** -Page and Section Headings and Subheadings -***************************************** - -Headings not only provide order and sections within a page, but they also -are used to automatically build both the page and document table of contents. -Headings are formed by using certain characters as underlines for a bit of -text. Major headings, like page titles and section headings also use -overlines. Other headings just use underlines, with the following hierarchy:: - - # with overline for page titles - * with overline for major sections - = for subsections - - for subsubsections - ^ for subsubsubsections - " for subsubsubsubsections (!) - -The :download:`TextMate ELDocs Bundle <./ELDocs.tmbundle.zip>` can help you -create these with the following tab triggers:: - - title-> - - ########## - Page Title - ########## - - sec-> - - ************* - Major Section - ************* - - sub-> - - Subsection - ========== - - sss-> - - SubSubSection - ------------- - - ssss-> - - SubSubSubSection - ^^^^^^^^^^^^^^^^ - - sssss-> - - SubSubSubSubSection (!) - """"""""""""""""""""""" - -********** -References -********** - -To a Section -============ - -If you need to link to a specific section, the first you add the label before a header:: - - .. _curlrequest-request-options-headers: - - headers - ======= - -And then you can reference it like this:: - - See :ref:`CURLRequest Class ` for how to add. - - See :ref:`curlrequest-request-options-headers` for how to add. - -To a Section in the Page -======================== - -You can reference a section in the current page like the following:: - - See `Result Rows`_ - -To a Page -========= - -You can reference a page like the following:: - - See :doc:`Session <../libraries/sessions>` library - - See :doc:`../libraries/sessions` library - -To a URL -======== - -:: - - `CodeIgniter 4 framework `_ - -To a Function -============= - -:: - - :php:func:`dot_array_search()` - -To a Method -=========== - -:: - - :php:meth:`CodeIgniter\\HTTP\\Response::setCookie()` - -**************** -Other Directives -**************** - -New Feature -=========== - -:: - - .. versionadded:: 4.3.0 - -Deprecated -========== - -:: - - .. deprecated:: 4.3.0 - Use :php:meth:`CodeIgniter\\Database\\BaseBuilder::setData()` instead. - -*************** -Text Decoration -*************** - -As a general rule, we use ``**`` for in-line file paths, and `````` for source code. - -E.g.:: - - Open the **app/Config/Filters.php** file and update the ``$methods`` property like the following: - -********** -Code Block -********** - -CLI Command -=========== - -:: - - .. code-block:: console - - php spark migrate diff --git a/contributing/pull_request.md b/contributing/pull_request.md index 844d62046cfa..9f1f8c28a24b 100644 --- a/contributing/pull_request.md +++ b/contributing/pull_request.md @@ -121,15 +121,15 @@ then you will need to add to the documentation. New classes, methods, parameters, changing default values, changing behavior etc. are all changes that require a change to documentation. -Also, the [Changelog](https://codeigniter4.github.io/CodeIgniter4/changelogs/index.html) +Also, the [Changelog](https://codeigniter4.github.io/CodeIgniter4/develop/changelogs/index.html) must be updated for every change, and PHPDoc blocks must be maintained. -See [Writing CodeIgniter Documentation](./documentation.rst). +See [Writing CodeIgniter Documentation](./documentation.md). #### Changelog -The [Changelog](https://codeigniter4.github.io/CodeIgniter4/changelogs/index.html) -in the [user guide](https://github.com/codeigniter4/CodeIgniter4/tree/develop/user_guide_src/source/changelogs) +The [Changelog](https://codeigniter4.github.io/CodeIgniter4/develop/changelogs/index.html) +in the [user guide](https://github.com/codeigniter4/CodeIgniter4/tree/develop/docs/changelogs) needs to be kept up-to-date. Not all changes will need an entry in it, but the following items should. @@ -144,8 +144,8 @@ following items should. If your PR requires users to do something when they upgrade CodeIgniter, or changes the Config values, -the [Upgrading Guide](https://codeigniter4.github.io/CodeIgniter4/installation/upgrading.html) -in the [installation](https://github.com/codeigniter4/CodeIgniter4/tree/develop/user_guide_src/source/installation) +the [Upgrading Guide](https://codeigniter4.github.io/CodeIgniter4/develop/installation/upgrading.html) +in the [installation](https://github.com/codeigniter4/CodeIgniter4/tree/develop/docs/installation) folder is also needed. - Add an instruction what to do when upgrading. diff --git a/tests/README.md b/tests/README.md index 4e35d026e838..3d55356baa35 100644 --- a/tests/README.md +++ b/tests/README.md @@ -54,7 +54,7 @@ database.default.port = 3306 Make sure that you provide a database engine that is currently running on your machine. More details on a test database setup are in the -[Testing Your Database](https://codeigniter4.github.io/CodeIgniter4/testing/database.html) section of the documentation. +[Testing Your Database](https://codeigniter4.github.io/CodeIgniter4/develop/testing/database.html) section of the documentation. If you want to run the tests without using live database you can exclude `@DatabaseLive` group. This will make the tests run quite a bit faster. diff --git a/tests/system/Database/Builder/UpdateTest.php b/tests/system/Database/Builder/UpdateTest.php index 91b220b0ba1b..7df08aea74f6 100644 --- a/tests/system/Database/Builder/UpdateTest.php +++ b/tests/system/Database/Builder/UpdateTest.php @@ -422,7 +422,7 @@ public function testUpdateWithWhereSameColumn3(): void } /** - * @see https://codeigniter4.github.io/CodeIgniter4/database/query_builder.html#updating-data + * @see https://codeigniter4.github.io/CodeIgniter4/develop/database/query_builder.html#updating-data */ public function testSetWithoutEscape(): void { diff --git a/tests/system/Database/Live/UpdateTest.php b/tests/system/Database/Live/UpdateTest.php index 41efa9b86c17..c23084a5b5f0 100644 --- a/tests/system/Database/Live/UpdateTest.php +++ b/tests/system/Database/Live/UpdateTest.php @@ -491,7 +491,7 @@ public function testUpdatePeriods(): void } /** - * @see https://codeigniter4.github.io/CodeIgniter4/database/query_builder.html#updating-data + * @see https://codeigniter4.github.io/CodeIgniter4/develop/database/query_builder.html#updating-data */ public function testSetWithoutEscape(): void {