From bfe471d5e499721b00ff02f9efdc4128e81dd00d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= <ciaranainsworth@posteo.net>
Date: Wed, 20 Mar 2019 13:29:33 +0100
Subject: [PATCH] Resolve "Document the documentation process"

---
 docs/admin/troubleshooting.rst      |   6 +-
 docs/documentation/creating.rst     | 129 ++++++++++++++++++++++++++++
 docs/documentation/identifying.rst  |  29 +++++++
 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.rst                      |   1 +
 docs/users/troubleshooting.rst      |   5 +-
 10 files changed, 483 insertions(+), 6 deletions(-)
 create mode 100644 docs/documentation/creating.rst
 create mode 100644 docs/documentation/identifying.rst
 create mode 100644 docs/documentation/index.rst
 create mode 100644 docs/documentation/rearrange.rst
 create mode 100644 docs/documentation/restructured.rst
 create mode 100644 docs/documentation/style.rst
 create mode 100644 docs/documentation/tools.rst

diff --git a/docs/admin/troubleshooting.rst b/docs/admin/troubleshooting.rst
index b547df6eb..a8c6f2546 100644
--- a/docs/admin/troubleshooting.rst
+++ b/docs/admin/troubleshooting.rst
@@ -159,6 +159,6 @@ similar issues before doing that, and use the issue tracker only to report bugs,
 Improving this documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you feel like something should be improved in this document (and in the documentation in general), feel free to `edit
-it <https://dev.funkwhale.audio/funkwhale/funkwhale/tree/develop/docs>`_ and open a Merge Request. If you lack time or skills
-to do that, you can open an issue to discuss that, and someone else will do it.
+If you feel like something should be improved in this document (and in the documentation in general), feel free to :doc:`contribute to the documentation <../documentation/creating>`.
+If you're not comfortable contributing or would like to ask somebody else to do it, feel free to :doc:`request a change in documentation <../documentation/identifying>`.
+
diff --git a/docs/documentation/creating.rst b/docs/documentation/creating.rst
new file mode 100644
index 000000000..57045896a
--- /dev/null
+++ b/docs/documentation/creating.rst
@@ -0,0 +1,129 @@
+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.
+
diff --git a/docs/documentation/identifying.rst b/docs/documentation/identifying.rst
new file mode 100644
index 000000000..eed1dc2f3
--- /dev/null
+++ b/docs/documentation/identifying.rst
@@ -0,0 +1,29 @@
+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://socialhub.network/c/funkwhale>`_ with more details about your requests
+- Ask somebody on our `chat room <https://riot.im/app/#/room/#funkwhale:matrix.org>`_
+
diff --git a/docs/documentation/index.rst b/docs/documentation/index.rst
new file mode 100644
index 000000000..15f0c76bb
--- /dev/null
+++ b/docs/documentation/index.rst
@@ -0,0 +1,28 @@
+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
+
diff --git a/docs/documentation/rearrange.rst b/docs/documentation/rearrange.rst
new file mode 100644
index 000000000..1110d1f22
--- /dev/null
+++ b/docs/documentation/rearrange.rst
@@ -0,0 +1,71 @@
+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.
+
diff --git a/docs/documentation/restructured.rst b/docs/documentation/restructured.rst
new file mode 100644
index 000000000..fcdde8aab
--- /dev/null
+++ b/docs/documentation/restructured.rst
@@ -0,0 +1,114 @@
+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.
+
diff --git a/docs/documentation/style.rst b/docs/documentation/style.rst
new file mode 100644
index 000000000..627831f6f
--- /dev/null
+++ b/docs/documentation/style.rst
@@ -0,0 +1,38 @@
+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.
+
diff --git a/docs/documentation/tools.rst b/docs/documentation/tools.rst
new file mode 100644
index 000000000..1de3141e1
--- /dev/null
+++ b/docs/documentation/tools.rst
@@ -0,0 +1,68 @@
+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.
+
diff --git a/docs/index.rst b/docs/index.rst
index 77bc83e0b..05f7ecbd8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -17,6 +17,7 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in
    admin/index
    developers/index
    third-party
+   documentation/index
    contributing
    translators
    changelog
diff --git a/docs/users/troubleshooting.rst b/docs/users/troubleshooting.rst
index d3254adfe..818e13bcb 100644
--- a/docs/users/troubleshooting.rst
+++ b/docs/users/troubleshooting.rst
@@ -102,7 +102,6 @@ similar issues before doing that, and use the issue tracker only to report bugs,
 Improving this documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you feel like something should be improved in this document (and in the documentation in general), feel free to `edit
-it <https://dev.funkwhale.audio/funkwhale/funkwhale/tree/develop/docs>`_ and open a Merge Request. If you lack time or skills
-to do that, you can open an issue to discuss that, and someone else will do it.
+If you feel like something should be improved in this document (and in the documentation in general), feel free to :doc:`contribute to the documentation <../documentation/creating>`.
+If you're not comfortable contributing or would like to ask somebody else to do it, feel free to :doc:`request a change in documentation <../documentation/identifying>`.