From ba240856507fea507cc65ec0dfe96a3415006cb7 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Thu, 21 May 2026 09:34:58 +0200 Subject: [PATCH 1/2] docs: improve README and CONTRIBUTING for contributors - README: restructure with Contributing, CoC, Getting help sections; slim contributing block to point to CONTRIBUTING.md; add Talk room link; drop GitHub Discussions (disabled); uv as primary build tool - CONTRIBUTING: add Code of Conduct section; uv as primary setup path, plain venv as fallback; update sphinx-autobuild install to use uv Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: skjnldsv --- CONTRIBUTING.md | 44 +++++--- README.rst | 285 +++++++++++++++++++++--------------------------- 2 files changed, 153 insertions(+), 176 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c9f540af09..20f3ae21d3b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,18 +8,24 @@ developer manuals. ## Table of Contents -1. [Where to ask questions](#where-to-ask-questions) -2. [Setting up a local build environment](#setting-up-a-local-build-environment) -3. [Making changes](#making-changes) -4. [Opening a pull request](#opening-a-pull-request) -5. [Commit message format](#commit-message-format) -6. [DCO sign-off](#dco-sign-off) -7. [Review process](#review-process) -8. [Style guide](#style-guide) -9. [Issue templates](#issue-templates) +1. [Code of Conduct](#code-of-conduct) +2. [Where to ask questions](#where-to-ask-questions) +3. [Setting up a local build environment](#setting-up-a-local-build-environment) +4. [Making changes](#making-changes) +5. [Opening a pull request](#opening-a-pull-request) +6. [Commit message format](#commit-message-format) +7. [DCO sign-off](#dco-sign-off) +8. [Review process](#review-process) +9. [Style guide](#style-guide) +10. [Issue templates](#issue-templates) --- +## Code of Conduct + +All contributors are expected to follow the +[Nextcloud Code of Conduct](https://nextcloud.com/contribute/code-of-conduct/). + ## Where to ask questions - **GitHub Discussions / Issues** – open an issue in this repository for @@ -36,7 +42,9 @@ developer manuals. Documentation is built with [Sphinx](https://www.sphinx-doc.org/). A local build lets you preview changes accurately before opening a PR. -### Using a Python virtual environment (recommended) +### Using uv (recommended) + +[uv](https://docs.astral.sh/uv/) is the fastest way to get started: ```bash # 1. Clone the repository @@ -44,16 +52,24 @@ git clone https://github.com/nextcloud/documentation.git cd documentation # 2. Create and activate a virtual environment -python3 -m venv venv -source venv/bin/activate # on Windows: venv\Scripts\activate +uv venv && source .venv/bin/activate # on Windows: .venv\Scripts\activate # 3. Install dependencies -pip install -r requirements.txt +uv pip install -r requirements.txt # 4. Build HTML (all manuals) make html ``` +### Using a plain Python virtual environment + +```bash +python3 -m venv venv +source venv/bin/activate # on Windows: venv\Scripts\activate +pip install -r requirements.txt +make html +``` + The built HTML files appear under each manual's `_build/html/` directory, e.g. `user_manual/_build/html/index.html`. @@ -67,7 +83,7 @@ then run `make html` in the integrated terminal. ### Live-reload while editing ```bash -pip install sphinx-autobuild +uv pip install sphinx-autobuild cd user_manual # or admin_manual / developer_manual make SPHINXBUILD=sphinx-autobuild html # Open http://127.0.0.1:8000 in your browser diff --git a/README.rst b/README.rst index f0eaec39b96..ff168be779e 100644 --- a/README.rst +++ b/README.rst @@ -2,226 +2,187 @@ Nextcloud Documentation ======================= -|build| |netlify| +|build| |netlify| |license| .. |build| image:: https://img.shields.io/github/actions/workflow/status/nextcloud/documentation/sphinxbuild.yml?branch=master&style=flat-square - :alt: Build Status + :target: https://github.com/nextcloud/documentation/actions/workflows/sphinxbuild.yml + :alt: Build status .. |netlify| image:: https://img.shields.io/badge/Netlify-powered-00C7B7?style=flat-square&logo=netlify :target: https://www.netlify.com :alt: Netlify -Documentation is published on ``_. -To edit it yourself, you need to tinker a bit with Git and Sphinx. -See the `Style Guide `_ for formatting and style conventions. +.. |license| image:: https://img.shields.io/badge/license-CC%20BY%203.0-lightgrey?style=flat-square + :target: https://creativecommons.org/licenses/by/3.0/deed.en_US + :alt: License: CC BY 3.0 + +Documentation for Nextcloud, published at `docs.nextcloud.com `_. +Written in reStructuredText and built with `Sphinx `_. + +New here? See `Contributing`_ below — we welcome all improvements, big or small. Manuals ------- This repository hosts three manuals: -* **Users' Manual** -* **Administration Manual** -* **Developers Manual** +* **User manual** — end-user features and workflows +* **Administration manual** — server installation, configuration, and operations +* **Developer manual** — app development, APIs, and architecture -Please work in the appropriate branch: ``stable``-branches are for the respective release (e.g. 14.0 or 15.0), ``master`` is the latest version. +Use the correct branch for the version you are targeting: ``master`` tracks the latest +release; ``stable`` branches (e.g. ``stable32``) cover specific releases. -Wrap prose lines at **120 characters** where practical. Long URLs, code -examples, and table cells may exceed this limit. See the -`Style Guide `_ -for full guidance. +.. note:: + ``configuration_server/config_sample_php_parameters.rst`` is auto-generated from + `config.sample.php in nextcloud/server `_. + Do not edit it here — changes must be made upstream in the server repository. -.. note:: ``configuration_server/config_sample_php_parameters.rst`` is auto-generated from the core - config.sample.php file; changes to this file must be made in core ``_ +Contributing +------------ -Spelling and Capitalization Conventions ---------------------------------------- +Contributions of any size are welcome — fixing a typo is just as valuable as writing a +new page. See `CONTRIBUTING.md `_ for the full workflow: local setup, +branch strategy, commit format, DCO sign-off, and review process. -As this grows it may be moved to its own page. +Quick entry points: -* Nextcloud App Store -* synchronize -* Web (Web page, Web site) +* **Report a problem** — `open an issue + `_ +* **Edit on GitHub** — fork the repo and open a pull request for small fixes +* **Write locally** — set up a build environment (see `Building`_) for larger changes +* **Translate** — `help on Transifex + `_ -License -------- +Before writing, read the `style guide `_. + +Code of Conduct +--------------- -All documentation in this repository is licensed under the Creative Commons -Attribution 3.0 Unported license (`CC BY 3.0`_). +All contributors are expected to follow the `Nextcloud Code of Conduct +`_. -.. _CC BY 3.0: https://creativecommons.org/licenses/by/3.0/deed.en_US +Getting help +------------ -Style ------ +* `Nextcloud community forums `_ — general Nextcloud questions +* `Documentation Talk room `_ — real-time chat + with documentation contributors +* `GitHub Issues `_ — bug reports and + documentation gaps -Source files are written using the `Sphinx Documentation Generator -`_. The syntax follows the `reStructuredText -`_ style, and can also be edited -from GitHub. +Structure policy +^^^^^^^^^^^^^^^^ -Structure ---------- +Once a page is created, **do not rename or move it** without adding a redirect in that +manual's ``conf.py``. External links and search-engine indexes depend on stable URLs — +treat page paths like a public API. -Of course, think about structure. Keep in mind that we try NOT to move or rename -pages once they are created! Lots of external sources link to our documentation, -including the indexing by search engines of course. So once you create a page with a certain -name, it has to stay in that location and with that name. Think of it as API stability -- we have to ensure things stay as they are as much as possible. Renaming or moving -is only allowed in exceptional circumstances and only when a redirect is put in place. +Spelling conventions +^^^^^^^^^^^^^^^^^^^^ -Editing -------- +* Nextcloud App Store +* synchronize (not "sync" in prose) +* Web, Web page, Web site (capitalised) + +Building +-------- -Contributing to the documentation requires a GitHub account. Make sure you are -working in the correct branch for your version of Nextcloud or client apps. -If your edits pertain to multiple manual versions, be prepared to backport as -needed. +Quick start +^^^^^^^^^^^ -To edit a document, you can edit the .rst files on your local system, or work -directly on GitHub. The latter is only suitable for small fixes and improvements -because substantial editing efforts can better be controlled on your local PC. +.. code-block:: bash -.. tip:: - If you're getting to know our documentation syntax, `give Documatt Snippets - `_ a try. This online editor is a great way - to practice with reStructuredText and Sphinx, and it provides a more accurate - preview of your work than GitHub does. + git clone https://github.com/nextcloud/documentation.git + cd documentation + uv venv && source .venv/bin/activate # recommended + uv pip install -r requirements.txt + make html # all manuals -The best way is to install a complete Sphinx build environment and work on your -local PC. You will be able to make your own local builds, which is the fastest -and best way to preview for errors. Sphinx will report syntax errors, missing -images, and formatting errors. The GitHub preview is not complete and misses -many mistakes. Create a new branch against the master or stable branch you are -editing, make your edits, then push your new branch to GitHub and open a new PR. +Using plain Python instead:: -To edit on GitHub, fork the repository (see top-right of the screen, under -your username). You will then be able to make changes easily. Once done, -you can create a pull request and get the changes reviewed and back into -the official repository. + python3 -m venv venv && source venv/bin/activate + pip install -r requirements.txt + make html -When editing either on your own local PC or on GitHub, be sure to sign of -commits, to certify adherence to the Developer Certificate of Origin, -see https://github.com/probot/dco . Your commit messages need to have, -the name and email address of the contributor. +Output lands in ``/_build/html/``. Build a single manual:: - Signed-off-by: Awesome Contributor + cd user_manual && make html -If using the command line and your name and email are configured, you can use +Autobuilding +^^^^^^^^^^^^ - git commit -s -m 'Commit message' +For a live-reloading preview while editing: -In both settings be sure that your email address matches that in your GitHub profile, -which if you have privacy enabled will be github.username@users.noreply.github.com +.. code-block:: bash + uv pip install sphinx-autobuild + cd user_manual + make SPHINXBUILD=sphinx-autobuild html -Translations ------------- +Then open http://127.0.0.1:8000. -`Help translate the documentation `_. +Translated versions (user manual only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For developers that want to ease the translation process, please read `this documentation `_. +1. Build the English version first (see above). +2. Generate translation stubs:: -Building --------- + ../build/change_file_extension.sh -Nightly Automated Build Steps -============================= +3. Build a specific language, e.g. German:: -1. **Fetch sources** - 1. ``git clone https://github.com/nextcloud/documentation.git`` - 2. ``cd documentation`` - 3. ``git checkout `` -2. **Install** - 1. ``pip3 install -r requirements.txt`` - 2. ``make all`` + make html-lang-de + Output: ``_build/html/de/index.html`` -Building HTML -============= +.. note:: Delete ``_build/`` before switching to a different language. -Using pipenv -^^^^^^^^^^^^ +PDF +^^^ -1. Install ``pipenv`` - https://pipenv.readthedocs.io/en/latest/ -2. Change into the environment: ``pipenv shell`` -3. Install the dependencies ``pip install -r requirements.txt`` -4. Now you can use ``make ...`` to build all the stuff - for example ``make html`` to build the HTML flavor of all manuals - The build assets will be put into the individual documentation subdirectories like ``developer_manual/_build/html/com`` +The easiest path is the `VSCode DevContainer +`_ or GitHub Codespaces — +all LaTeX dependencies are pre-installed. Open the repository in the container and run:: -To change into this environment you need to run ``pipenv shell`` to launch the shell and to exit you can use either ``exit`` or ``Ctrl`` + ``D``. + cd user_manual && make latexpdf -Using venv -^^^^^^^^^^ +Alternatively, use Docker directly: -1. Install ``python3-venv`` -2. Only once: Create a venv (typically inside this repository): ``python -m venv venv`` -3. Activate the environment (inside this repository): ``source venv/bin/activate`` -4. Install the dependencies ``pip install -r requirements.txt`` -5. Now you can use ``make ...`` to build all the stuff - for example ``make html`` to build the HTML flavor of all manuals - The build assets will be put into the individual documentation subdirectories like ``developer_manual/_build/html/com`` +.. code-block:: bash -Building translated versions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + docker run --platform linux/amd64 \ + --volume .:/docs --interactive --tty \ + ghcr.io/nextcloud/documentation/sphinx-latex:latest bash -Only available in user_manual: + # Inside the container: + cd /docs && python3 -m venv venv && source venv/bin/activate + pip install -r requirements.txt + cd user_manual && make latexpdf + # Output: _build/latex/Nextcloud_User_Manual.pdf -1. Build the english version as described above before -2. Create translation files: ``../build/change_file_extension.sh`` -3. Create German (``de``) version: ``make html-lang-de`` -4. Find the HTML files in ``_build/html/de/index.html`` -5. Before building another language you have to delete the complete ``_build`` directory +For translated PDFs (user manual only), generate translation stubs first +(``../build/change_file_extension.sh``), then run ``make latexpdf-lang-de``. -Autobuilding -^^^^^^^^^^^^ +.. note:: + Installing LaTeX locally is not recommended due to the large number of system + dependencies. Use the DevContainer or Docker approach instead. -When editing the documentation installing ``sphinx-autobuild`` though pip can be helpful. This will watch file changes and automatically reload the html preview: - -1. Install ``pip install sphinx-autobuild`` -2. When building the developer documentation make sure to execute ``make openapi-spec`` in the repository root -3. Enter the documentation section ``cd user_manual`` -4. Watch for file changes ``make SPHINXBUILD=sphinx-autobuild html`` -5. Open http://127.0.0.1:8000 in the browser and start editing - -Building PDF -============ - -Building inside docker -^^^^^^^^^^^^^^^^^^^^^^ - -1. Create a docker:: ``docker run --platform linux/amd64 --volume .:/docs --interactive --tty --name nextcloud-docs ghcr.io/nextcloud/continuous-integration-documentation:documentation-15 bash`` -2. Change into the documentation directory: ``cd /docs`` -3. Only once: Create a venv: ``python -m venv venv`` -4. Activate the environment: ``source venv/bin/activate`` -5. Install the dependencies ``pip install -r requirements.txt`` -6. Change into the documentation of choice (admin, developer, user): ``cd /docs/user_manual`` -7. To build the English version: ``make latexpdf`` -8. To build the translated version (only available in user_manual): - 1. Create translation files: ``../build/change_file_extension.sh`` - 2. Create German (``de``) version: ``make latexpdf-lang-de`` - 3. Find the file in ``_build/latex/Nextcloud_User_Manual.pdf`` - 4. Before building another language you have to delete the complete ``_build`` directory - -Building locally -^^^^^^^^^^^^^^^^ +Translations +------------ -.. note:: Because of the many dependencies LaTeX and the other tools bring in, it is not recommended to install the tools locally. +`Help translate the documentation on Transifex +`_. -1. Follow instructions for "Building HTML" above -2. Install ``latexmk`` and ``texlive-latex-extra`` - https://pipenv.readthedocs.io/en/latest/ -3. Create a Python environment (typically inside this repository): ``pipenv --python 3.9`` -4. Change into the environment: ``pipenv shell`` -5. Install the dependencies ``pip install -r requirements.txt`` -6. Now you can use ``make ...`` to build all the stuff - for example ``make pdf`` to build the PDF flavor of all manuals +Translation files under ``locale/`` are managed by Transifex and synced via CI. +Edit source strings in ``.rst`` files only — never edit ``locale/`` directly. -Using the VSCode DevContainer -============================= +For the Transifex Sphinx integration, see the +`Transifex documentation `_. -This repository contains a full-featured `VSCode DevContainer `_. -You can use it in your local development environment or via `GitHub Codespaces `_. -Just open the container an use one of the commands from above to build the project. For example ``make`` to build the full -documentation, ``make html`` to build the HTML documentation or ``make pdf`` to build the PDF documentation. You can also use -``make SPHINXBUILD=sphinx-autobuild html`` in combination with `port forwarding `_ -to watch file changes and automatically reload the html preview. +License +------- -.. _CC BY 3.0: https://creativecommons.org/licenses/by/3.0/deed.en_US -.. _`Xcode command line tools`: https://stackoverflow.com/questions/9329243/xcode-install-command-line-tools +All documentation in this repository is licensed under the `Creative Commons +Attribution 3.0 Unported license (CC BY 3.0) +`_. From 5ea31ba4aaa3e4964b675134d50e2575328ef122 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Thu, 21 May 2026 09:39:06 +0200 Subject: [PATCH 2/2] docs: remove em dashes; add Python version to uv venv Replace all em dashes with colons or semicolons throughout README.rst and CONTRIBUTING.md. Add `--python 3.13` to uv venv commands with a note that older stable branches may require a different version. Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: skjnldsv --- CONTRIBUTING.md | 14 +++++++++----- README.rst | 43 ++++++++++++++++++++++++------------------- 2 files changed, 33 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 20f3ae21d3b..88c09fc7fe3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,13 +46,17 @@ build lets you preview changes accurately before opening a PR. [uv](https://docs.astral.sh/uv/) is the fastest way to get started: +The Python version below matches `master`. If you are building an older `stable` branch, +check that branch's CI configuration for the required Python version and adjust +the `--python` flag accordingly. + ```bash # 1. Clone the repository git clone https://github.com/nextcloud/documentation.git cd documentation # 2. Create and activate a virtual environment -uv venv && source .venv/bin/activate # on Windows: .venv\Scripts\activate +uv venv --python 3.13 && source .venv/bin/activate # on Windows: .venv\Scripts\activate # 3. Install dependencies uv pip install -r requirements.txt @@ -64,7 +68,7 @@ make html ### Using a plain Python virtual environment ```bash -python3 -m venv venv +python3.13 -m venv venv source venv/bin/activate # on Windows: venv\Scripts\activate pip install -r requirements.txt make html @@ -123,7 +127,7 @@ versions, etc.). ``` 5. Open a pull request against the appropriate branch of `nextcloud/documentation`. -6. Fill in the pull request template — include a screenshot of changed pages +6. Fill in the pull request template; include a screenshot of changed pages where relevant. --- @@ -145,7 +149,7 @@ Signed-off-by: Your Name | Type | When to use | | ---------- | ------------------------------------------------------------ | -| `docs` | Content changes — new or updated documentation text | +| `docs` | Content changes: new or updated documentation text | | `fix` | Correcting errors (broken links, wrong commands, typos, …) | | `feat` | Adding a new page or section | | `refactor` | Restructuring without changing the meaning of the content | @@ -201,7 +205,7 @@ GitHub's privacy setting enabled, it will be 2. Automated checks (spelling, link validation) run on every PR. Fix any reported issues before requesting a re-review. 3. The reviewer may request changes. Address feedback and push new commits to - the same branch — do **not** force-push after a review has started. + the same branch; do **not** force-push after a review has started. 4. Once approved, a maintainer will merge the PR. --- diff --git a/README.rst b/README.rst index ff168be779e..31332545799 100644 --- a/README.rst +++ b/README.rst @@ -19,16 +19,16 @@ Nextcloud Documentation Documentation for Nextcloud, published at `docs.nextcloud.com `_. Written in reStructuredText and built with `Sphinx `_. -New here? See `Contributing`_ below — we welcome all improvements, big or small. +New here? See `Contributing`_ below. We welcome all improvements, big or small. Manuals ------- This repository hosts three manuals: -* **User manual** — end-user features and workflows -* **Administration manual** — server installation, configuration, and operations -* **Developer manual** — app development, APIs, and architecture +* **User manual**: end-user features and workflows +* **Administration manual**: server installation, configuration, and operations +* **Developer manual**: app development, APIs, and architecture Use the correct branch for the version you are targeting: ``master`` tracks the latest release; ``stable`` branches (e.g. ``stable32``) cover specific releases. @@ -36,22 +36,22 @@ release; ``stable`` branches (e.g. ``stable32``) cover specific releases. .. note:: ``configuration_server/config_sample_php_parameters.rst`` is auto-generated from `config.sample.php in nextcloud/server `_. - Do not edit it here — changes must be made upstream in the server repository. + Do not edit it here; changes must be made upstream in the server repository. Contributing ------------ -Contributions of any size are welcome — fixing a typo is just as valuable as writing a +Contributions of any size are welcome. Fixing a typo is just as valuable as writing a new page. See `CONTRIBUTING.md `_ for the full workflow: local setup, branch strategy, commit format, DCO sign-off, and review process. Quick entry points: -* **Report a problem** — `open an issue +* **Report a problem**: `open an issue `_ -* **Edit on GitHub** — fork the repo and open a pull request for small fixes -* **Write locally** — set up a build environment (see `Building`_) for larger changes -* **Translate** — `help on Transifex +* **Edit on GitHub**: fork the repo and open a pull request for small fixes +* **Write locally**: set up a build environment (see `Building`_) for larger changes +* **Translate**: `help on Transifex `_ Before writing, read the `style guide `_. @@ -65,17 +65,17 @@ All contributors are expected to follow the `Nextcloud Code of Conduct Getting help ------------ -* `Nextcloud community forums `_ — general Nextcloud questions -* `Documentation Talk room `_ — real-time chat +* `Nextcloud community forums `_: general Nextcloud questions +* `Documentation Talk room `_: real-time chat with documentation contributors -* `GitHub Issues `_ — bug reports and +* `GitHub Issues `_: bug reports and documentation gaps Structure policy ^^^^^^^^^^^^^^^^ Once a page is created, **do not rename or move it** without adding a redirect in that -manual's ``conf.py``. External links and search-engine indexes depend on stable URLs — +manual's ``conf.py``. External links and search-engine indexes depend on stable URLs; treat page paths like a public API. Spelling conventions @@ -91,17 +91,22 @@ Building Quick start ^^^^^^^^^^^ +.. note:: + The Python version below matches ``master``. If you are building an older + ``stable`` branch, check that branch's CI configuration for the required version + and adjust the ``--python`` flag accordingly. + .. code-block:: bash git clone https://github.com/nextcloud/documentation.git cd documentation - uv venv && source .venv/bin/activate # recommended + uv venv --python 3.13 && source .venv/bin/activate # recommended uv pip install -r requirements.txt - make html # all manuals + make html # all manuals Using plain Python instead:: - python3 -m venv venv && source venv/bin/activate + python3.13 -m venv venv && source venv/bin/activate pip install -r requirements.txt make html @@ -142,7 +147,7 @@ PDF ^^^ The easiest path is the `VSCode DevContainer -`_ or GitHub Codespaces — +`_ or GitHub Codespaces; all LaTeX dependencies are pre-installed. Open the repository in the container and run:: cd user_manual && make latexpdf @@ -175,7 +180,7 @@ Translations `_. Translation files under ``locale/`` are managed by Transifex and synced via CI. -Edit source strings in ``.rst`` files only — never edit ``locale/`` directly. +Edit source strings in ``.rst`` files only; never edit ``locale/`` directly. For the Transifex Sphinx integration, see the `Transifex documentation `_.