MirrorMirror
/
funkwhale
mirror of https://dev.funkwhale.audio/funkwhale/funkwhale.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rewrite documentation contributor guide

This commit is contained in:
Ciarán Ainsworth 2022-10-25 16:51:47 +00:00
parent 03d6369b9c
commit 80912e7bb4
12 changed files with 128 additions and 479 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
changes/changelog.d/docs_rewrite.doc Normal file
View File

@ -0,0 +1 @@
Rewrote documentation contributor guide.

112
docs/contributor_documentation/documentation.md Normal file
View File

@ -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)

11
docs/contributor_documentation/index.md Normal file
View File

@ -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.

2
docs/developer_documentation/index.md
View File

@ -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.

129
docs/documentation/creating.rst
View File

@ -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 <tools>` to get started
- Check the `current documents <https://docs.funkwhale.audio>`_ carefully to make sure you're not repeating something somebody has already said
- Familiarize yourself with :doc:`reStructuredText <restructured>` and :doc:`the recommended document style <style>`
Once you're ready to get started, you can start :ref:`working with Gitlab <work-with-gitlab>`
.. _work-with-gitlab:
Working With Gitlab
-------------------
Documents are managed in the Funkwhale `Gitlab <https://dev.funkwhale.audio>`_ repository along with the code.
In order to add new documents, you will need to follow this process:
- :ref:`Sign up to Gitlab <sign-up>`
- :ref:`Fork the project <fork-project>`
- :ref:`Clone the Repository <clone-repo>`
- :ref:`Add documents to your branch <add-docs>`
- :ref:`Create a Merge Request <merge-request>`
.. _sign-up:
Signing up to Gitlab
^^^^^^^^^^^^^^^^^^^^
Before you can contribute documents to Funkwhale, you will need to set up an account on the
project's `Gitlab <https://dev.funkwhale.audio>`_. To do this:
- Navigate to the https://dev.funkwhale.audio
- Click on "register" to bring up the registration form
- Fill in the relevant details, or alternatively sign up with Github if you already have an account
- [Optional]: You can then `set up an SSH key <https://docs.gitlab.com/ee/ssh/>`_ to enable easy management of your :ref:`repository <clone-repo>`
.. _fork-project:
Fork the project
^^^^^^^^^^^^^^^^
Once you have set up an account, you can `fork the project <https://help.github.com/en/articles/fork-a-repo>`_
to create a copy of the repository that you can make changes to.
- Navigate to the `Funkwhale repository <https://dev.funkwhale.audio/funkwhale/funkwhale>`_
- Click "Fork" at the top of the repository
- You will be redirected to a new version of the project. This one's all yours!
.. _clone-repo:
Clone the Repository
^^^^^^^^^^^^^^^^^^^^
Once you have successfully forked the project, you can safely download a copy of this to your local
computer to create documents.
.. code-block:: shell
# If you're using an SSH key
git clone git@dev.funkwhale.audio:your-username/funkwhale.git
# If you're using a username/password
git clone https://dev.funkwhale.audio/your-username/funkwhale.git
Once you've cloned the repository, it's a good idea to create a new branch for your documents so that
you can :ref:`merge it later <merge-request>`
.. code-block:: shell
# Create a new branch to make changes to
git checkout -b [name_of_your_new_branch]
# Push the branch up to your forked repository
git push origin [name_of_your_new_branch]
.. _add-docs:
Add Documents to Your Branch
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When you've got your repository all set up, you can start writing your documents. Remember to keep in mind
:doc:`who you are writing for <style>` when you are writing, and :doc:`check your syntax works <restructured>`.
Once you've written what you need to write, you can push these changes to your forked repository:
.. code-block:: shell
# Add new documents to your commit
git add [list your documents here]
# Commit these to the branch
git commit -m "Add a commit message here!"
# Push the changes to your branch
git push origin [name_of_your_new_branch]
.. _merge-request:
Create a Merge Request
^^^^^^^^^^^^^^^^^^^^^^
Once you've pushed all of your documents, you can create a `Merge Request <https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html>`_
to request the documents be merged into the official Funkwhale develop branch.
- Navigate to the `Funkwhale repository <https://dev.funkwhale.audio/funkwhale/funkwhale>`_
- Click "Merge Requests" on the left hand side
- Click on the "New Merge Request"
- Under the "Source Branch" select your forked repository and the branch to which you've pushed changes
- Under "Target Branch", select the "develop" branch
- Click "Compare Branches and Continue"
- In the form that comes up, provide a title/description of the changes you've made
- Click "Submit Merge Request" to submit
That's it! If your merge request is successful, you will get a notification from one of the maintainers letting
you know your changes have been accepted. Sometimes, you may need to make minor corrections. Don't worry! We'll
let you know what needs correcting.

28
docs/documentation/identifying.rst
View File

@ -1,28 +0,0 @@
Identifying Gaps in Funkwhale Documentation
===========================================
As Funkwhale and its community continue to grow and develop, more and more processes and features
will need to be documented. As users find interesting new ways to interact with the software,
provide novel solutions to existing issues, and find information they need missing, the documents
will need to be updated and added to.
If you are trying to do something in Funkwhale and can't find any
resources to help, you can help out by contributing in one of the following ways:
Providing Documentation
-----------------------
If you've identified a gap or mistake in the documentation and feel comfortable writing up new
guides/correcting existing ones, please feel free to do so. The best way to do this is by following
the :doc:`document creation guide <creating>` to make sure your documents get processed as quickly
as possible.
Requesting Documentation
------------------------
If you're not comfortable with writing documents or don't feel like you can, you can help out
by requesting a document be written. There are three ways to request new documents:
- Open a new issue on `Gitlab <https://dev.funkwhale.audio/funkwhale/funkwhale/issues>`_, providing as much detail as possible
- Start a new thread on `the forum <https://forum.funkwhale.audio/>`_ with more details about your requests
- Ask somebody on our `chat room <https://matrix.to/#/#funkwhale:matrix.org>`_

28
docs/documentation/index.rst
View File

@ -1,28 +0,0 @@
Contribute to Funkwhale's Documentation
=======================================
Funkwhale is constantly growing and changing, so good documentation is essential.
If you find a gap or mistake in existing documents, or you want to create new documents
to cover something that isn't covered yet, you can follow this procedure to contribute
to Funkwhale's documentation store.
Setup
-----
.. toctree::
:maxdepth: 2
identifying
tools
restructured
Contributing
------------
.. toctree::
:maxdepth: 2
style
creating
rearrange

71
docs/documentation/rearrange.rst
View File

@ -1,71 +0,0 @@
Rearranging Files
=================
Sometimes, rearranging the layout of documents in the docs folder can help to make
things a bit clearer for users. However, this can present the following issues:
- :ref:`Orphaned document links <orphaned-doc>`
- :ref:`Orphaned URLs <orphaned-url>`
.. _orphaned-doc:
Orphaned Document Links
-----------------------
Documents frequently reference other documents to avoid repeating information. If you
move a document, you need to be sure to update any orphaned references.
Running ``make html`` in the ``docs`` directory (assuming you have :doc:`Sphinx installed <tools>`)
will generate a series of warnings letting you know if any links are orphaned.
.. code-block:: shell
funkwhale/docs/documentation/rearrange.rst:17: WARNING: unknown document: setup
You can then go to the file/line in question and update the link to its new location.
.. _orphaned-url:
Orphaned URLs
-------------
Once internal document links have been resolved, it is important to consider that the
moved file may have also been linked externally elsewhere before. In order to ensure
that anybody trying to access the file is properly redirected to its new location, we
need to make use of the link redirector in the ``conf.py`` file.
The link redirector takes two arguments: the old location of the file (passed as a .html
file at the relative path ``docs``), and the new location it should redirect to. For example,
if a document was moved from ``docs/index.html`` to ``docs/admin/index.html``, we would add
the following to the ``redirect_files`` section of ``conf.py``:
.. code-block:: python
# -- Build legacy redirect files -------------------------------------------
# Define list of redirect files to be build in the Sphinx build process
redirect_files = [
('index.html', 'admin/index.html')
]
If you are moving something from one folder to another, you would need to tell the redirect
to move to the correct level. For example, if a file is moving from ``docs/admin/index.html``
to ``docs/users/index.html``, you will need to add the following to the ``redirect_files``
section of ``conf.py``:
.. code-block:: python
# -- Build legacy redirect files -------------------------------------------
# Define list of redirect files to be build in the Sphinx build process
redirect_files = [
('admin/index.html', '../users/index.html') #The '..' tells the script to go up a level
]
The script will then take these two arguments and create a redirect file in the original
location so that anybody accessing the existing URL will be redirected.

114
docs/documentation/restructured.rst
View File

@ -1,114 +0,0 @@
Writing reStructuredText
========================
Funkwhale's documentation is written using a standard markup language called
`reStructuredText <http://docutils.sourceforge.net/rst.html>`_. It is similar to Markdown
and other web-based markup languages, but is better suited to technical documentation
due to its standardized nature. A full syntax breakdown can be found `here <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_,
but the following should be enough to get you started on writing docs for Funkwhale.
Headings
--------
Headings are useful for splitting up text into relevant subsections. With `Sphinx <http://www.sphinx-doc.org/>`_,
major headers and direct subheaders are rendered as navigation links on Index pages, which
makes them ideal for sharing specific information quickly.
Headers are written like so:
.. code-block:: rst
Header 1 //Equivalent to <h1>
========
Header 2 //Equivalent to <h2>
--------
Header 3 //Equivalent to <h3>
^^^^^^^^
.. note::
Underlines should be **at least** as long as the words they underline
Links
-----
Links can be rendered in several different ways depending on where they link to:
.. code-block:: rst
`external link <https://example-url/>`_
:doc:`link to document <../relative/doc/path>`
Inline references can also be generated using the following syntax:
.. code-block:: rst
:ref:`This links to the text <link-ref>`
.. _link-ref:
The text you want to jump to
Lists
-----
Bullet point lists are usually written using dashes like so:
.. code-block:: rst
- Item 1
- Item 2
- Item 3
Blocks
------
Blocks can be used to easily and concisely present information to a reader and are
particularly useful when demonstrating technical steps. Blocks in reStructuredText can
be written as follows:
.. code-block:: rst
.. code-block:: shell
write terminal commands here
.. code-block:: python
write Python code here
.. code-block:: text
write text here
Other syntax highlighting is available. See the spec for full details.
.. note::
Content within code blocks should be indented by three spaces. You can end the code block by
removing the indent.
Notes and Warnings
------------------
Notes are great for presenting important information to users and providing additional context.
Warnings can be very useful if a step you're writing about could potentially have adverse consequences.
.. code-block:: rst
.. note::
Your note goes here
.. warning::
Your warning goes here!
.. note::
Content within notes and warnings should be indented by three spaces. You can end the block by
removing the indent.

38
docs/documentation/style.rst
View File

@ -1,38 +0,0 @@
Documentation Style Guide
=========================
End-user Documentation
----------------------
End-user documentation is often the most difficult to write as it requires striking the right balance
between technical and non-technical instruction. Typically, writing a document should start
with you asking yourself the following question:
Why is the user reading this document?
The answer will usually be one of the following:
- They are new to the project and are looking to learn more about it
- They are trying to do something and are having difficulty
Documentation should be written with these two answers in mind. Information should be
clearly laid out in small sections with plenty of clear examples and precise instructions.
You should also try to pre-empt where the user might need to go next in order to ease their
journey through the document by providing logical and relevant links to more documents.
Administrator Documentation
---------------------------
Funkwhale is quite a technical project and is enjoyed by people who like setting up their own
systems. These users can range from experienced server administrators to hobbyists, so administrator
documentation should include plenty of technical instructions with an easy-to-read explanation of each
step to cover both use-cases.
Developer Documentation
-----------------------
Developer documentation should aim to be as technical and readable as possible. Since
the reader is likely a developer themselves, providing as much technical detail as possible
is the best course of action as it allows them to dive in to the project's internals with
more confidence. It is safe to assume they are used to reading more technical work.

68
docs/documentation/tools.rst
View File

@ -1,68 +0,0 @@
Documentation Requirements
==========================
Funkwhale's documentation is written using :doc:`reStructuredText <restructured>` and is built using
`Sphinx <http://www.sphinx-doc.org/>`_.
Text Editor
-----------
As reStructuredText is a writing standard, any text editor can be used to modify documents depending on preference.
User-friendly programs such as `Retext <https://github.com/retext-project/retext>`_ are good options for
those just getting started with writing reStructuredText. Many other editors such as `Vim <https://www.vim.org/>`_,
`Emacs <https://www.gnu.org/software/emacs/>`_, `VS Code <https://code.visualstudio.com/>`_, and
`Atom <https://atom.io/>`_ have addons which can help with syntax highlighting and live previewing.
Sphinx
------
Sphinx is used to generate a static site based on the ``.rst`` files in the ``docs`` directory. When writing
documents, it can be useful to build the site to see how your changes will look in production. To do this:
- Install Sphinx using `pip <https://pypi.org/project/pip/>`_
.. code-block:: shell
pip install sphinx
- Navigate to your local ``funkwhale/docs`` directory
.. code-block:: shell
cd funkwhale/docs
- Use the make file to build the site
.. code-block:: shell
make html
- Sphinx will generate the site in your ``funkwhale/docs/_build`` directory unless otherwise stated
Once you have generated a local copy of the site, you can open it up by opening the index.html file in
``funkwhale/docs/_build``.
.. note::
If you are familiar with `Docker <https://www.docker.com/>`_ and `docker-compose <https://docs.docker.com/compose/>`_,
you can also hack on the documentation via a single command: ``docker-compose -f dev.yml up docs``.
This will make the documentation available at http://0.0.0.0:8001, with live-reloading enabled, so any change made in the
``.rst`` files will be reflected immediately in your browser.
Git
---
In order to work on files on your computer, you will need to install `git <https://git-scm.com/>`_ for your
operating system. Git is used to push and pull files to and from the Funkwhale repository and track changes
made to documents/code alike.
Gitlab
------
If you are only making minor changes to a document or don't wish to install anything, you can use
`Gitlab's <https://dev.funkwhale.audio>`_ built-in IDE. Once you have made an account and :doc:`created
a pull request <creating>`, you can click on the "Open in Web IDE" button to open up a fully-fledged
editor in your web browser.

5
docs/index.md
View File

@ -88,7 +88,8 @@ caption: Contributor documentation
hidden: true
---
documentation/index
contributor_documentation/index
contributor_documentation/documentation
translators
```
@ -215,7 +216,7 @@ Want to help make Funkwhale even better? Check out these guides for some ideas.
+++
```{button-link} contributing.html
```{button-link} contributor_documentation/index.html
:ref-type: ref
:color: primary
:outline: