From 9680e59a396b51f1eb0acd523ffda3efc6d2e1c4 Mon Sep 17 00:00:00 2001 From: smiley Date: Tue, 11 Jul 2023 14:26:37 +0200 Subject: [PATCH] :octocat: --- docs/Readme.md | 58 ++++++++++++++++++++++++++++++++++---------------- docs/conf.py | 7 ++++-- docs/index.rst | 2 +- 3 files changed, 46 insertions(+), 21 deletions(-) diff --git a/docs/Readme.md b/docs/Readme.md index f38c79062..8098db98a 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -1,27 +1,13 @@ # Documentation -## Sources - -The markdown sources for the [Read the Docs online manual](https://php-qrcode.readthedocs.io) can of course be browsed on GitHub too! - - -### Usage -- [Overview](./Usage-Overview.md) -- [Installation](./Usage-Installation.md) -- [Quickstart](./Usage-Quickstart.md) -- [Advanced usage](./Usage-Advanced-usage.md) - -### Appendix -- [License](./Appendix-License.rst) - ## Auto generated documentation ### User manual via Sphinx -[![Documentation Status](https://readthedocs.org/projects/php-qrcode/badge/?version=latest)](https://php-qrcode.readthedocs.io/en/latest/?badge=latest) +[![Documentation Status](https://readthedocs.org/projects/php-qrcode/badge/?version=main)](https://php-qrcode.readthedocs.io/en/main/?badge=main) The user manual can be auto generated with [Sphinx](https://www.sphinx-doc.org) from the markdown sources contained in this directory, in order to upload it to [Read the Docs](https://readthedocs.org). -The online documentation can be found at [php-qrcode.readthedocs.io](https://php-qrcode.readthedocs.io) ([project page](https://readthedocs.org/projects/php-qrcode/)) +The online documentation can be found at [php-qrcode.readthedocs.io](https://php-qrcode.readthedocs.io/en/main/) ([project page](https://readthedocs.org/projects/php-qrcode/)), a local copy is built during CI and stored in the [`readthedocs` branch](https://github.com/chillerlan/php-qrcode/tree/readthedocs). #### Run Sphinx locally @@ -29,7 +15,7 @@ The online documentation can be found at [php-qrcode.readthedocs.io](https://php Requirements: - [Python](https://www.python.org/downloads/) >= v3.10 - - [Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html) >= v7.0 + - [Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html) >= v6.0 - [Sphinx RTD theme](https://pypi.org/project/sphinx-rtd-theme/) >= 1.2 - [MyST Parser](https://myst-parser.readthedocs.io/en/latest/intro.html) >= 2.0 (see [Sphinx Markdown configuration](https://www.sphinx-doc.org/en/master/usage/markdown.html#markdown)) @@ -43,13 +29,15 @@ Requirements: ### API docs via phpDocumentor + [![pages-build-deployment](https://github.com/chillerlan/php-qrcode/actions/workflows/pages/pages-build-deployment/badge.svg?branch=gh-pages)](https://github.com/chillerlan/php-qrcode/actions/workflows/pages/pages-build-deployment) The API documentation can be auto generated with [phpDocumentor](https://www.phpdoc.org/). -There is an [online version available](https://chillerlan.github.io/php-qrcode/) via the [gh-pages branch](https://github.com/chillerlan/php-qrcode/tree/gh-pages) that is [automatically deployed](https://github.com/chillerlan/php-qrcode/deployments) on each push to main. +There is an [online version available](https://chillerlan.github.io/php-qrcode/) via the [`gh-pages` branch](https://github.com/chillerlan/php-qrcode/tree/gh-pages) that is [automatically deployed](https://github.com/chillerlan/php-qrcode/deployments) on each push to main. #### Run phpDocumentor locally + If you'd like to create local docs, please follow these steps: - [download phpDocumentor](https://github.com/phpDocumentor/phpDocumentor/releases) v3+ as .phar archive @@ -60,6 +48,40 @@ If you'd like to create local docs, please follow these steps: - profit! +## Sources + +The markdown sources for the [Read the Docs online manual](https://php-qrcode.readthedocs.io) can of course be browsed on GitHub too! + + +### Usage +- [Overview](./Usage-Overview.md) +- [Installation](./Usage-Installation.md) +- [Quickstart](./Usage-Quickstart.md) +- [Advanced usage](./Usage-Advanced-usage.md) + + +### Customizing output +- [Module values](./Customizing-Module-Values.md) +- [Custom output interface](./Customizing-Custom-output-interface.md) +- [QROutputAbstract](./Customizing-QROutputAbstract.md) + + +### Examples +- [Built-in Output Interfaces](./Examples-Built-in.md) + + +### Public API +- [`QRCode`](./API-QRCode.md) +- [`QROptions`](./API-QROptions.md) +- [`QROutputInterface`](./API-QROutputInterface.md) +- [`QRMatrix`](./API-QRMatrix.md) + + +### Appendix +- [Glossary](./Appendix-Glossary.md) +- [License](./Appendix-License.rst) + + ## License The documentation is licensed under the [Creative Commons Attribution 4.0 International (CC BY 4.0) License](https://creativecommons.org/licenses/by/4.0/). diff --git a/docs/conf.py b/docs/conf.py index 4a43a1fe3..3e72e9f4b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,9 +15,12 @@ import sys from subprocess import Popen, PIPE def get_version(): - if os.environ.get('READTHEDOCS') == 'True': + if os.environ.get('READTHEDOCS') == True: return os.environ.get('READTHEDOCS_VERSION') + if os.environ.get('GITHUB_ACTIONS') == True: + return os.environ.get('GITHUB_REF_NAME') + grep = 'git branch | findstr \*' if platform.system() == 'Windows' else 'git branch | grep \*' pipe = Popen(grep, stdout=PIPE, shell=True, universal_newlines=True) version = pipe.stdout.read() @@ -65,7 +68,7 @@ release = version # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '5.3.0' +needs_sphinx = '6.0.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom diff --git a/docs/index.rst b/docs/index.rst index f7249db54..6c485d687 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,7 @@ PHP-QRCode Manual ================= -Edition for ``chillerlan/php-qrcode`` [|version|]. Updated on |today|. +Edition for `chillerlan/php-qrcode `__ [|version|]. Updated on |today|. This work is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) License.