From bca5dc23862fffed4ceaf03afde3428a0e9dedca Mon Sep 17 00:00:00 2001 From: BK Date: Wed, 6 Dec 2023 07:18:24 +1100 Subject: [PATCH 1/2] Docs: explain: pagy + retype, add contribution instructions Why? To document hidden steps. --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index fce4937b7..8f3ee2a7f 100644 --- a/README.md +++ b/README.md @@ -358,6 +358,26 @@ See also the [How To Page](https://ddnexus.github.io/pagy/docs/how-to) - For simple contribution you can quickly check your changes with the [Pagy::Console](https://ddnexus.github.io/pagy/docs/api/console/) or with the single file [pagy_standalone_app.ru](https://github.com/ddnexus/pagy/blob/master/apps/pagy_standalone_app.ru). - If you Create A Pull Request, please ensure that the "All checks have passed" indicator gets green light on the Pull Request page (if it's not enabled, a maintainer will enable it for you). + +### Documentation Contributions + +Documentation contributions or suggestions are welcome. + +1. Download [`retype`](https://retype.com/guides/cli/) +2. `retype start` in the pagy root directory. + +And your docs should appear in a browser. + +#### Primer on how Pagy's Documentation works + +Pagy's documentation is built on [retype](https://retype.com/). + +Pagy uses a [github action](https://github.com/ddnexus/pagy/blob/master/.github/workflows/retype-action.yml) to trigger the build process i.e. the docs need to be "built". Why? Because the docs are written in [markdown format](https://en.wikipedia.org/wiki/Markdown) - however, markdown is not sufficient to deliver html to your browser. Retype does the hard work of converting that markdown into html with styling. + +Once built, then [Github pages](https://pages.github.com/) delivers it to you. But we must tell Github to deliver the html that has been created. Where is the html located? The html - i.e. the "built" site - is located in the root directory of the [`docs-site` branch](https://github.com/ddnexus/pagy/tree/docs-site) of the Pagy repository. The admin of the repository can set the branch that is used in the settings section of the repository. + +More details on the docs are available on the [retype website](https://retype.com/guides/github-actions/). The Pagy repository is using the Open Source version, subject to certain limitations (i.e. total page count). [Pro version](https://retype.com/pro/) opens up other benefits. +
From bb969f6c358a29691db0a08923b0c8ba084bdc36 Mon Sep 17 00:00:00 2001 From: BK Date: Wed, 6 Dec 2023 15:24:59 +1100 Subject: [PATCH 2/2] Docs: add separate readme.md section, exclude from retype --- README.md | 21 +-------------------- docs/README.md | 24 ++++++++++++++++++++++++ retype.yml | 1 + 3 files changed, 26 insertions(+), 20 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index 8f3ee2a7f..019769d2e 100644 --- a/README.md +++ b/README.md @@ -251,6 +251,7 @@ See also the [How To Page](https://ddnexus.github.io/pagy/docs/how-to) - [How To (quick recipes)](https://ddnexus.github.io/pagy/docs/how-to/) - [Changelog](https://ddnexus.github.io/pagy/changelog) - [Deprecations](https://ddnexus.github.io/pagy/changelog#deprecations) +- [How Pagy's Docs work?](https://github.com/ddnexus/pagy/blob/master/docs/README.md)
@@ -358,26 +359,6 @@ See also the [How To Page](https://ddnexus.github.io/pagy/docs/how-to) - For simple contribution you can quickly check your changes with the [Pagy::Console](https://ddnexus.github.io/pagy/docs/api/console/) or with the single file [pagy_standalone_app.ru](https://github.com/ddnexus/pagy/blob/master/apps/pagy_standalone_app.ru). - If you Create A Pull Request, please ensure that the "All checks have passed" indicator gets green light on the Pull Request page (if it's not enabled, a maintainer will enable it for you). - -### Documentation Contributions - -Documentation contributions or suggestions are welcome. - -1. Download [`retype`](https://retype.com/guides/cli/) -2. `retype start` in the pagy root directory. - -And your docs should appear in a browser. - -#### Primer on how Pagy's Documentation works - -Pagy's documentation is built on [retype](https://retype.com/). - -Pagy uses a [github action](https://github.com/ddnexus/pagy/blob/master/.github/workflows/retype-action.yml) to trigger the build process i.e. the docs need to be "built". Why? Because the docs are written in [markdown format](https://en.wikipedia.org/wiki/Markdown) - however, markdown is not sufficient to deliver html to your browser. Retype does the hard work of converting that markdown into html with styling. - -Once built, then [Github pages](https://pages.github.com/) delivers it to you. But we must tell Github to deliver the html that has been created. Where is the html located? The html - i.e. the "built" site - is located in the root directory of the [`docs-site` branch](https://github.com/ddnexus/pagy/tree/docs-site) of the Pagy repository. The admin of the repository can set the branch that is used in the settings section of the repository. - -More details on the docs are available on the [retype website](https://retype.com/guides/github-actions/). The Pagy repository is using the Open Source version, subject to certain limitations (i.e. total page count). [Pro version](https://retype.com/pro/) opens up other benefits. -
diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..58df0bc79 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,24 @@ +### Documentation Contributions + +Documentation contributions or suggestions are welcome. + +1. Download [`retype`](https://retype.com/guides/cli/) +2. `retype start` in the pagy root directory. + +And your docs should appear in a browser. + +#### Primer on how Pagy's Documentation works + +Pagy's documentation is built on [retype](https://retype.com/). + +All of [retype's configuration](https://retype.com/configuration/project/) is located in the [`retype.yml` file](https://github.com/ddnexus/pagy/blob/master/retype.yml). + +Pagy uses a [github action](https://github.com/ddnexus/pagy/blob/master/.github/workflows/retype-action.yml) to trigger the build process i.e. the docs need to be "built". Why? Because the docs are written in [markdown format](https://en.wikipedia.org/wiki/Markdown) - however, markdown is not sufficient to deliver html to your browser. Retype does the hard work of converting that markdown into html with styling. + +Once built, then [Github pages](https://pages.github.com/) delivers it to you. But we must tell Github to deliver the html that has been created. Where is the html located? The html - i.e. the "built" site - is located in the root directory of the [`docs-site` branch](https://github.com/ddnexus/pagy/tree/docs-site) of the Pagy repository. The admin of the repository can set the branch that is used in the settings section of the repository. + +More details on the docs are available on the [retype website](https://retype.com/guides/github-actions/). + +The Pagy repository is using the Open Source version, subject to certain limitations (i.e. total page count). [Pro version](https://retype.com/pro/) opens up other benefits. Credit to: [Retypeapp](https://github.com/retypeapp) and +[@geoffreymcgill](https://github.com/geoffreymcgill) and possibly others behind the scenes. + diff --git a/retype.yml b/retype.yml index 61ae23082..4fd9494b7 100644 --- a/retype.yml +++ b/retype.yml @@ -40,6 +40,7 @@ exclude: - e2e/README.md - test/README.md - lib/**/README.md + - docs/README.md edit: repo: "https://github.com/ddnexus/pagy"