diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c9f540af09..88c09fc7fe3 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,13 @@ 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: + +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 @@ -44,16 +56,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 --python 3.13 && 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.13 -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 +87,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 @@ -107,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. --- @@ -129,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 | @@ -185,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 f0eaec39b96..31332545799 100644 --- a/README.rst +++ b/README.rst @@ -2,226 +2,192 @@ 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 `_. -All documentation in this repository is licensed under the Creative Commons -Attribution 3.0 Unported license (`CC BY 3.0`_). +Code of Conduct +--------------- -.. _CC BY 3.0: https://creativecommons.org/licenses/by/3.0/deed.en_US +All contributors are expected to follow the `Nextcloud Code of Conduct +`_. -Style ------ +Getting help +------------ -Source files are written using the `Sphinx Documentation Generator -`_. The syntax follows the `reStructuredText -`_ style, and can also be edited -from GitHub. +* `Nextcloud community forums `_: general Nextcloud questions +* `Documentation Talk room `_: real-time chat + with documentation contributors +* `GitHub Issues `_: bug reports and + documentation gaps -Structure ---------- +Structure policy +^^^^^^^^^^^^^^^^ -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. +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. -Editing -------- +Spelling conventions +^^^^^^^^^^^^^^^^^^^^ -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. +* Nextcloud App Store +* synchronize (not "sync" in prose) +* Web, Web page, Web site (capitalised) -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. +Building +-------- -.. 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. +Quick start +^^^^^^^^^^^ -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. +.. 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. -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. +.. code-block:: bash -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. + git clone https://github.com/nextcloud/documentation.git + cd documentation + uv venv --python 3.13 && source .venv/bin/activate # recommended + uv pip install -r requirements.txt + make html # all manuals - Signed-off-by: Awesome Contributor +Using plain Python instead:: -If using the command line and your name and email are configured, you can use + python3.13 -m venv venv && source venv/bin/activate + pip install -r requirements.txt + make html - git commit -s -m 'Commit message' +Output lands in ``/_build/html/``. Build a single manual:: -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 + cd user_manual && make html +Autobuilding +^^^^^^^^^^^^ -Translations ------------- +For a live-reloading preview while editing: -`Help translate the documentation `_. +.. code-block:: bash -For developers that want to ease the translation process, please read `this documentation `_. + uv pip install sphinx-autobuild + cd user_manual + make SPHINXBUILD=sphinx-autobuild html -Building --------- +Then open http://127.0.0.1:8000. -Nightly Automated Build Steps -============================= +Translated versions (user manual only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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`` +1. Build the English version first (see above). +2. Generate translation stubs:: + ../build/change_file_extension.sh -Building HTML -============= +3. Build a specific language, e.g. German:: -Using pipenv -^^^^^^^^^^^^ + make html-lang-de -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`` + Output: ``_build/html/de/index.html`` -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``. +.. note:: Delete ``_build/`` before switching to a different language. -Using venv -^^^^^^^^^^ +PDF +^^^ -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`` +The easiest path is the `VSCode DevContainer +`_ or GitHub Codespaces; +all LaTeX dependencies are pre-installed. Open the repository in the container and run:: -Building translated versions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + cd user_manual && make latexpdf -Only available in user_manual: +Alternatively, use Docker directly: -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 +.. code-block:: bash -Autobuilding -^^^^^^^^^^^^ + docker run --platform linux/amd64 \ + --volume .:/docs --interactive --tty \ + ghcr.io/nextcloud/documentation/sphinx-latex:latest bash -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 -^^^^^^^^^^^^^^^^ + # 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 -.. note:: Because of the many dependencies LaTeX and the other tools bring in, it is not recommended to install the tools locally. +For translated PDFs (user manual only), generate translation stubs first +(``../build/change_file_extension.sh``), then run ``make latexpdf-lang-de``. -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 +.. note:: + Installing LaTeX locally is not recommended due to the large number of system + dependencies. Use the DevContainer or Docker approach instead. -Using the VSCode DevContainer -============================= +Translations +------------ + +`Help translate the documentation on Transifex +`_. + +Translation files under ``locale/`` are managed by Transifex and synced via CI. +Edit source strings in ``.rst`` files only; never edit ``locale/`` directly. -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. +For the Transifex Sphinx integration, see the +`Transifex documentation `_. + +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) +`_.