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

Resolve "Document the documentation process"

This commit is contained in:
Ciarán Ainsworth 2019-03-20 13:29:33 +01:00 committed by Eliot Berriot
parent 75785ee001
commit 507387e8e3
10 changed files with 483 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/admin/troubleshooting.rst
View File

@ -159,6 +159,6 @@ similar issues before doing that, and use the issue tracker only to report bugs,
Improving this documentation Improving this documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you feel like something should be improved in this document (and in the documentation in general), feel free to `edit 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>`.
it <https://dev.funkwhale.audio/funkwhale/funkwhale/tree/develop/docs>`_ and open a Merge Request. If you lack time or skills 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>`.
to do that, you can open an issue to discuss that, and someone else will do it.

129
docs/documentation/creating.rst Normal file
View File

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

29
docs/documentation/identifying.rst Normal file
View File

@ -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>`_

28
docs/documentation/index.rst Normal file
View File

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

71
docs/documentation/rearrange.rst Normal file
View File

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

114
docs/documentation/restructured.rst Normal file
View File

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

38
docs/documentation/style.rst Normal file
View File

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

68
docs/documentation/tools.rst Normal file
View File

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

1
docs/index.rst
View File

@ -17,6 +17,7 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in
admin/index admin/index
developers/index developers/index
third-party third-party
documentation/index
contributing contributing
translators translators
changelog changelog

5
docs/users/troubleshooting.rst
View File

@ -102,7 +102,6 @@ similar issues before doing that, and use the issue tracker only to report bugs,
Improving this documentation Improving this documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you feel like something should be improved in this document (and in the documentation in general), feel free to `edit 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>`.
it <https://dev.funkwhale.audio/funkwhale/funkwhale/tree/develop/docs>`_ and open a Merge Request. If you lack time or skills 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>`.
to do that, you can open an issue to discuss that, and someone else will do it.