From 80912e7bb47020ae7d66affe0a9803fea4d44ea3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Tue, 25 Oct 2022 16:51:47 +0000 Subject: [PATCH] Rewrite documentation contributor guide --- changes/changelog.d/docs_rewrite.doc | 1 + .../documentation.md | 112 +++++++++++++++ docs/contributor_documentation/index.md | 11 ++ docs/developer_documentation/index.md | 2 +- docs/documentation/creating.rst | 129 ------------------ docs/documentation/identifying.rst | 28 ---- docs/documentation/index.rst | 28 ---- docs/documentation/rearrange.rst | 71 ---------- docs/documentation/restructured.rst | 114 ---------------- docs/documentation/style.rst | 38 ------ docs/documentation/tools.rst | 68 --------- docs/index.md | 5 +- 12 files changed, 128 insertions(+), 479 deletions(-) create mode 100644 changes/changelog.d/docs_rewrite.doc create mode 100644 docs/contributor_documentation/documentation.md create mode 100644 docs/contributor_documentation/index.md delete mode 100644 docs/documentation/creating.rst delete mode 100644 docs/documentation/identifying.rst delete mode 100644 docs/documentation/index.rst delete mode 100644 docs/documentation/rearrange.rst delete mode 100644 docs/documentation/restructured.rst delete mode 100644 docs/documentation/style.rst delete mode 100644 docs/documentation/tools.rst diff --git a/changes/changelog.d/docs_rewrite.doc b/changes/changelog.d/docs_rewrite.doc new file mode 100644 index 000000000..b9d8b7b38 --- /dev/null +++ b/changes/changelog.d/docs_rewrite.doc @@ -0,0 +1 @@ +Rewrote documentation contributor guide. diff --git a/docs/contributor_documentation/documentation.md b/docs/contributor_documentation/documentation.md new file mode 100644 index 000000000..a5b1d6610 --- /dev/null +++ b/docs/contributor_documentation/documentation.md @@ -0,0 +1,112 @@ +# Contribute to Funkwhale documentation + +```{tip} +If you notice something missing in our documentation but don't feel confident contributing, submit a request [in our forum](https://forum.funkwhale.audio/t/documentation). +``` + +We try to document Funkwhale as thoroughly as possible to make it easy for users, admins, developers, and contributors to understand how everything works. + +```{contents} +:local: +``` + +## Requirements + +To work on Funkwhale's documentation, you need the following: + +- [Git](https://git-scm.com): our version control system +- [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/): used to run our development environment +- A text editor of your choice + +## Tooling + +We use [Sphinx](https://www.sphinx-doc.org/) to generate our documentation. Sphinx provides excellent tooling for documenting Python projects. We write documentation in Markdown using the [MyST parser](https://myst-parser.readthedocs.io/en/latest/) to access Sphinx's features. + +All documentation in Funkwhale is stored in the [main Funkwhale Git repository](https://dev.funkwhale.audio/funkwhale/funkwhale/-/tree/develop/docs). + +## Style guide + +We broadly follow the [Microsoft writing style guide](https://learn.microsoft.com/en-us/style-guide/welcome/) for language and tone. You should aim to keep your language simple and clear enough for readers of all levels. You can use a free tool like [Hemingway](https://hemingwayapp.com) to check the complexity of your sentences. + +Here are some basic rules to follow: + +1. Write in American English +2. Always use sentence casing for headers. For example: "Contribute to Funkwhale documentation" rather than "Contribute To Funkwhale Documentation" +3. Use contractions such as "don't" and "can't" to make your writing feel conversational. Only use the full words if you're trying to emphasize something + +## Local setup + +We provide a docker container for our documentation to make it easy to work on docs with a real-time preview. Once you install [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/), do the following to get a live preview: + +1. Create a dummy `.env` file + + ```{code-block} sh + touch .env + ``` + +2. Create a dummy federation network + + ```{code-block} sh + docker network create federation + ``` + +3. Build the container + + ```{code-block} sh + docker-compose -f dev.yml build docs + ``` + +4. Run the container + + ```{code-block} sh + docker-compose -f dev.yml up docs + ``` + +A real-time preview of the documentation is available on `http://0.0.0.1:8001` + +## Redirects + +If you move content to a new location, you need to set up a redirect. This ensures that any bookmarks or links posted before the change still take the user where they expect to go. + +All redirects are stored in a {file}`redirects.txt` file. This is a simple text file containing one redirect per line. Each line contains the old URL and new URL as relative URLs. + +In this example, the `architecture.html` file redirects to `https://docs.funkwhale.audio/developers/architecture.html`. + +```{code-block} text +architecture.html, developers/architecture.html +``` + +## Contribution flow + +Here's an example of the typical workflow for creating documentation: + +1. [Create a fork](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html) of the Funkwhale codebase +2. Create a new branch for your documentation. In this example `my-branch-name` is the name of the branch + + ```{code-block} sh + git checkout -b my-branch-name + ``` + +3. Make your changes and verify them by running the [Docker container](#local-setup) +4. Add [redirects](#redirects) if required +5. Add a [changelog fragment](../developer_documentation/workflows/changelog.md) +6. Add your changed files to a commit + + ```{code-block} sh + git add . # Add all changed files + git add doc1.md doc2.md # Add specific files + ``` + +7. Create a commit with a meaningful commit message + + ```{code-block} sh + git commit -m "A meaningful commit message" + ``` + +8. Push your changes to your fork + + ```{code-block} sh + git push origin my-branch-name + ``` + +9. Create a merge request in the [main Funkwhale repository](https://dev.funkwhale.audio/funkwhale/funkwhale) diff --git a/docs/contributor_documentation/index.md b/docs/contributor_documentation/index.md new file mode 100644 index 000000000..31775c904 --- /dev/null +++ b/docs/contributor_documentation/index.md @@ -0,0 +1,11 @@ +# Get started + +```{note} +Are you a software developer? Check out our [developer documentation](../developer_documentation/index.md) to contribute to our codebase. +``` + +Funkwhale is a community-led software project, so we depend on our community donating their time and skills. Whether you're experienced in a specific field or just starting out, we welcome any contributions and will support you with any task you take on. + +## Contribute to Funkwhale's documentation + +Got a knack for writing? Want to teach people how things work? Our [documentation guide](documentation.md) takes you through everything you need to know to contribute to the Funkwhale documentation hub. diff --git a/docs/developer_documentation/index.md b/docs/developer_documentation/index.md index e536c5faf..787b6effd 100644 --- a/docs/developer_documentation/index.md +++ b/docs/developer_documentation/index.md @@ -1,4 +1,4 @@ -# Developer documentation +# Get started Funkwhale welcomes contributions from all developers. If this is your first time contributing to an open source project, don't be afraid to get stuck in! The Funkwhale community will guide you through the process and help you grow your confidence. diff --git a/docs/documentation/creating.rst b/docs/documentation/creating.rst deleted file mode 100644 index 57045896a..000000000 --- a/docs/documentation/creating.rst +++ /dev/null @@ -1,129 +0,0 @@ -Adding New Documents -==================== - -Writing Documents ------------------ - -Before you start writing documents: - -- Make sure you have all the necessary information and :doc:`tools you need ` to get started -- Check the `current documents `_ carefully to make sure you're not repeating something somebody has already said -- Familiarize yourself with :doc:`reStructuredText ` and :doc:`the recommended document style