diff --git a/docs/admin/troubleshooting.rst b/docs/admin/troubleshooting.rst index b547df6ebc1e1822c3f3078a8a10df8a4e7c2d8d..a8c6f2546cad8b4ca1a456648d5ef9727b99d07c 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 0000000000000000000000000000000000000000..57045896abc93798f2dd4dc8d76ca05f8c9cc045 --- /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 0000000000000000000000000000000000000000..eed1dc2f3f9bb60d99b57b10e149ba41d4f46422 --- /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 0000000000000000000000000000000000000000..15f0c76bb3b79f43fbb0606344a2249f4fb5d1e2 --- /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 0000000000000000000000000000000000000000..1110d1f22ba803157a3a2bdc869ce8c121f7671c --- /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 0000000000000000000000000000000000000000..fcdde8aab1772cecea7327656fe11fe2da12f5e6 --- /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 0000000000000000000000000000000000000000..627831f6f8174509596730e34d0e8263719dcde4 --- /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 0000000000000000000000000000000000000000..1de3141e169f8d999d0e0779b39f9b536eac7811 --- /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 77bc83e0b96e9188c921b8c052f9d6c1287474c9..05f7ecbd81d4e525b69a1bc314e6ca72597c6a49 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 d3254adfe1a816a1b881c9b400d966de8c8eae23..818e13bcb52abd086143ce6e215b45afc71d4ae1 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>`.