diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..69fa449 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..99b360e --- /dev/null +++ b/Makefile @@ -0,0 +1,30 @@ +# -*- mode: makefile; -*- +# Copyright (C) 2022 Savoir-faire Linux Inc. +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . +# + +CMD ?= sphinx-build +OPTS ?= +SRC = . +OUT = _build + +# default rule +help: + @$(CMD) -M help "$(SRC)" "$(OUT)" $(OPTS) + +.PHONY: help Makefile + +%: Makefile + @$(CMD) -M $@ "$(SRC)" "$(OUT)" $(OPTS) diff --git a/_static/logo-jami.svg b/_static/logo-jami.svg new file mode 100644 index 0000000..5aa80f4 --- /dev/null +++ b/_static/logo-jami.svg @@ -0,0 +1,411 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/_templates/footer.html b/_templates/footer.html new file mode 100644 index 0000000..db3a703 --- /dev/null +++ b/_templates/footer.html @@ -0,0 +1,71 @@ +{# + Copyright (C) 2022 Savoir-faire Linux Inc. + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +The main purpose of this file is to enable use of a custom format +for the copyright statement in page footers, and is based on the +footer.html file from the Read the Docs Sphinx Theme project, under +the Expat License (also referred to as the "MIT License"), per the +following notice: + + Copyright (c) 2013-2018 Dave Snider, Read the Docs, Inc. & contributors + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, + TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +#} + +{% extends '!footer.html' %} +{% block contentinfo %} +

{%- if show_copyright %} + {%- if hasdoc('copyright') %} + {%- trans path=pathto('copyright'), copyright=copyright|e %}Copyright © {{ copyright }}.{% endtrans %} + {%- else %} + {%- trans copyright=copyright|e %}Copyright © {{ copyright }}.{% endtrans %} + {%- endif %} +{%- endif %} +{%- if build_id and build_url %} + + {#- Translators: Build is a noun, not a verb -#} + {%- trans %}Build{% endtrans -%} + {{ build_id }}. + +{%- elif commit %} + + {#- Translators: the phrase "revision" comes from Git, referring to a commit #} + {%- trans %}Revision{% endtrans %} {{ commit }}. + +{%- endif %} +{%- if last_updated %} + + {%- trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} + +{%- endif -%}

+{% endblock %} diff --git a/conf.py b/conf.py new file mode 100644 index 0000000..7fcb202 --- /dev/null +++ b/conf.py @@ -0,0 +1,42 @@ +# Copyright (C) 2022 Savoir-faire Linux Inc. +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . +# + +# for a full list of Sphinx configuration options, see: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +project = 'Jami' +copyright = '2018-2022 Savoir-faire Linux Inc. and contributors' +author = 'Savoir-faire Linux Inc. and contributors' + +extensions = [ +] + +templates_path = ['_templates'] + +exclude_patterns = ['_build'] + +html_theme = 'sphinx_rtd_theme' + +html_theme_options = { + 'navigation_depth': 3, + 'sticky_navigation': False, + 'collapse_navigation': False, +} + +# paths containing custom static files +# (copied after the builtin static files, so a "default.css" +# file there would overwrite the builtin "default.css") +html_static_path = ['_static'] diff --git a/guides/how-to-contribute-to-this-documentation.rst b/guides/how-to-contribute-to-this-documentation.rst new file mode 100644 index 0000000..976481d --- /dev/null +++ b/guides/how-to-contribute-to-this-documentation.rst @@ -0,0 +1,147 @@ +####################################### +How to contribute to this documentation +####################################### + +Contributions to these docs are always welcome and appreciated, from +small corrections to whole new chapters. + +This page will walk through the steps to create a new page or submit a +correction. The patch review process is the same as :doc:`for any +other Jami project `, so we will not explain +every command. + +**TODO: internationalization** + +Dependencies +============ + +You will need Git installed and configured to use your SSH keypair, +and an account on the Jami `Gerrit `_, where +you would send your patches for review. If you need help with this, +see :doc:`the beginning of our patch submission guide +` (TODO). + +If you want to preview your changes locally in your web browser, you +need to install `Sphinx `_. You also need +to install a markdown parser for Sphinx: + +.. code-block:: bash + + $ pip install --upgrade recommonmark + + +Cloning the repository +====================== + +Clone the repository and configure the push settings like this: + +.. code-block:: bash + + $ git clone "ssh://USERNAME@review.jami.net:29420/jami-docs.git" + $ cd jami-docs + $ git config remote.origin.push HEAD:refs/for/master + +You may want to checkout a new branch for each contribution/change +before you make any change to the files, so that you could easily +``git pull`` any future changes from upstream into your main local +branch: + +.. code-block:: bash + + $ git checkout -b my-example-change + +Editing a page +============== + +Pages are written in either markdown or `reStructuredText +`_. +You can click "View page source" at the top of any page to open the +raw source of the page and see how it was written. + +Go ahead and make your changes to the ``.rst`` or ``.md`` files. + +Previewing your work +==================== + +From the base of the repository, run: + +.. code-block:: bash + + $ make clean && make html + +You should now be able to view the documentation in your web +browser. The homepage is at ``_build/html/index.html``. + +Saving your work +================ + +.. code-block:: bash + + $ git add source/file/you/edited.md + $ git commit + +Your commit message should look something like this: + +.. code-block:: none + + Short summary of your change in present tense + + Longer description of your change in complete sentences, if necessary. + + Jami GitLab issue numbers (e.g. GitLab: #445), if relevant. + +For example: + +.. code-block:: none + + Add new page section to guides/how-to-contribute-to-this-documentation + + Add a new section explaining how to add a new page to these docs, + including listing it in the `toctree` directive of the containing + section/folder index. + + GitLab: #123 + +Submitting a change +=================== + +The first time you try to push your changes, Gerrit will complain that +you don't have a Change-Id in your commit, and provide an ``scp`` +command to install the commit hook. After running the command, you +should be able to recommit and push your change: + +.. code-block:: bash + + $ git commit --amend --no-edit + $ git push + + +Modifying your work +=================== + +A reviewer may ask you to make changes to your patch before merging +it. This is no problem! Simply make the changes, ``git add`` them, +and run ``git commit --amend`` to modify the patch. Note the +``--amend`` switch, which is needed to tell git to *amend*/tweak the +existing newest commit rather than making a new commit. This is the +workflow for updating a proposed change when using Gerrit. + +Adding a page +============= + +If you decide to add a whole new page to the documentation, you must +also add it to the ``toctree`` directive of that chapter. + +For instance, if you added a new guide called +``hosting-jams-on-aws.md`` in the ``guides`` folder, you should add it +in the ``toctree`` directive of ``guides/index.rst``, *without* the +file extension: + + +.. code-block:: reST + + .. toctree:: + + bug-report-guide + ... + hosting-jams-on-aws diff --git a/guides/index.rst b/guides/index.rst new file mode 100644 index 0000000..71e1e1d --- /dev/null +++ b/guides/index.rst @@ -0,0 +1,11 @@ +###### +Guides +###### + +These are how-to guides that should `follow this format +`_. + +.. toctree:: + :maxdepth: 1 + + how-to-contribute-to-this-documentation diff --git a/index.rst b/index.rst new file mode 100644 index 0000000..5d2bf18 --- /dev/null +++ b/index.rst @@ -0,0 +1,23 @@ +Home +==== + +.. image:: _static/logo-jami.svg + :alt: Jami logo + +This is the documentation for Jami, free software for universal +communication that respects the freedom and privacy of its users. + +This documentation is community-driven and :doc:`anyone can +contribute`! + +.. note:: You may also be interested in the Jami `daemon + `_ or `libclient + `_'s technical documentation, + the daemon's `code coverage `_, + or the `OpenDHT wiki + `_. + +.. toctree:: + :maxdepth: 2 + + guides/index