Skip to content

Commit 8d99254

Browse files
Any97CrisAny97Cris
authored
Merge pull request #29 from LibreSign/chore/add-readme-and-style-guide
chore: add readmne and styleguide
2 parents a742275 + f5351d8 commit 8d99254

File tree

4 files changed

+312
-2
lines changed

4 files changed

+312
-2
lines changed

‎README.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎README.rst‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
=======================
2+
LibreSign Documentation
3+
=======================
4+
5+
Documentation is published on `<https://docs.libresign.coop>`_.
6+
To edit it yourself, you need to tinker a bit with Git and Sphinx.
7+
See the `Style Guide <https://github.com/nextcloud/documentation/blob/master/style_guide.rst>`_ for formatting and style conventions.
8+
9+
Manuals
10+
-------
11+
12+
This repository hosts three manuals:
13+
14+
* **Users' Manual**
15+
* **Administration Manual**
16+
* **Developers Manual**
17+
18+
Please wrap lines at 80 characters.
19+
20+
Spelling and Capitalization Conventions
21+
---------------------------------------
22+
23+
* Nextcloud
24+
* LibreSign
25+
26+
License
27+
-------
28+
29+
All documentation in this repository is licensed under the Creative Commons
30+
Attribution 3.0 Unported license (`CC BY 3.0`_).
31+
32+
.. _CC BY 3.0: https://creativecommons.org/licenses/by/3.0/deed.en_US
33+
34+
Style
35+
-----
36+
37+
Source files are written using the `Sphinx Documentation Generator
38+
<https://www.sphinx-doc.org/en/master/>`_. The syntax follows the `reStructuredText
39+
<http://docutils.sourceforge.net/rst.html>`_ style, and can also be edited
40+
from GitHub.
41+
42+
Structure
43+
---------
44+
45+
Of course, think about structure. Keep in mind that we try NOT to move or rename
46+
pages once they are created! Lots of external sources link to our documentation,
47+
including the indexing by search engines of course. So once you create a page with a certain
48+
name, it has to stay in that location and with that name. Think of it as API stability
49+
- we have to ensure things stay as they are as much as possible. Renaming or moving
50+
is only allowed in exceptional circumstances and only when a redirect is put in place.
51+
52+
Editing
53+
-------
54+
55+
Contributing to the documentation requires a GitHub account.
56+
57+
To edit a document, you can edit the .rst files on your local system, or work
58+
directly on GitHub. The latter is only suitable for small fixes and improvements
59+
because substantial editing efforts can better be controlled on your local PC.
60+
61+
The best way is to install a complete Sphinx build environment and work on your
62+
local PC or using the docker-compose that stay at home folder of this repository.
63+
You will be able to make your own local builds, which is the fastest
64+
and best way to preview for errors. Sphinx will report syntax errors, missing
65+
images, and formatting errors. The GitHub preview is not complete and misses
66+
many mistakes. Create a new branch against the main, make your edits, then push
67+
your new branch to GitHub and open a new PR.
68+
69+
To edit on GitHub, fork the repository (see top-right of the screen, under
70+
your username). You will then be able to make changes easily. Once done,
71+
you can create a pull request and get the changes reviewed and back into
72+
the official repository.
73+
74+
When editing either on your own local PC or on GitHub, be sure to sign of
75+
commits, to certify adherence to the Developer Certificate of Origin,
76+
see https://github.com/probot/dco . Your commit messages need to have,
77+
the name and email address of the contributor.
78+
79+
Signed-off-by: Awesome Contributor <[email protected]>
80+
81+
If using the command line and your name and email are configured, you can use
82+
83+
git commit -s -m 'Commit message'
84+
85+
In both settings be sure that your email address matches that in your GitHub profile,
86+
which if you have privacy enabled will be [email protected]
87+
88+
89+
Building
90+
--------
91+
92+
Building HTML
93+
=============
94+
95+
Using pipenv
96+
^^^^^^^^^^^^
97+
98+
1. Install ``pipenv`` - https://pipenv.readthedocs.io/en/latest/
99+
2. Change into the environment: ``pipenv shell``
100+
3. Install the dependencies ``pip install -r docs/requirements.txt``
101+
4. Now you can use ``make ...`` to build all the stuff - for example ``make html`` to build the HTML flavor of all manuals
102+
The build assets will be put into the individual documentation subdirectories like ``developer_manual/_build/html/com``
103+
104+
To change into this environment you need to run ``pipenv shell`` to launch the shell and to exit you can use either ``exit`` or ``Ctrl`` + ``D``.
105+
106+
Using venv
107+
^^^^^^^^^^
108+
109+
1. Install ``python3-venv``
110+
2. Only once: Create a venv (typically inside this repository): ``python -m venv venv``
111+
3. Activate the environment (inside this repository): ``source venv/bin/activate``
112+
4. Install the dependencies ``pip install -r docs/requirements.txt``
113+
5. Now you can use ``make ...`` to build all the stuff - for example ``make html`` to build the HTML flavor of all manuals
114+
The build assets will be put into the individual documentation subdirectories like ``developer_manual/_build/html/com``
115+
116+
Autobuilding
117+
^^^^^^^^^^^^
118+
119+
When editing the documentation installing ``sphinx-autobuild`` though pip can be helpful. This will watch file changes and automatically reload the html preview:
120+
121+
1. Install ``pip install sphinx-autobuild``
122+
2. Enter the documentation section ``cd user_manual``
123+
3. Watch for file changes ``make SPHINXBUILD=sphinx-autobuild html``
124+
4. Open http://127.0.0.1:8000 in the browser and start editing
125+
126+
Building PDF
127+
============
128+
129+
1. Follow instructions for "Building HTML" above
130+
2. Install ``latexmk`` and ``texlive-latex-extra`` - https://pipenv.readthedocs.io/en/latest/
131+
3. Create a Python environment (typically inside this repository): ``pipenv --python 3.9``
132+
4. Change into the environment: ``pipenv shell``
133+
5. Install the dependencies ``pip install -r docs/requirements.txt``
134+
6. Now you can use ``make ...`` to build all the stuff - for example ``make pdf`` to build the PDF flavor of all manuals
135+
136+
Using the VSCode DevContainer
137+
=============================
138+
139+
This repository contains a full-featured `VSCode DevContainer <https://code.visualstudio.com/docs/devcontainers/containers>`_.
140+
You can use it in your local development environment or via `GitHub Codespaces <https://github.com/features/codespaces>`_.
141+
Just open the container an use one of the commands from above to build the project. For example ``make`` to build the full
142+
documentation, ``make html`` to build the HTML documentation or ``make pdf`` to build the PDF documentation. You can also use
143+
``make SPHINXBUILD=sphinx-autobuild html`` in combination with `port forwarding <https://code.visualstudio.com/docs/devcontainers/containers#_forwarding-or-publishing-a-port>`_
144+
to watch file changes and automatically reload the html preview.
145+
146+
Usign docker
147+
============
148+
You can also use the `docker-compose.yml` file to build the documentation using
149+
Docker. This is useful if you want to avoid installing Python and its
150+
dependencies on your local machine.
151+
152+
1. Make sure you have Docker and Docker Compose installed.
153+
2. Open a terminal and navigate to the root directory of the repository.
154+
3. Run the following command to build the documentation:
155+
156+
``docker-compose up``
157+
158+
This will build the HTML documentation and place it in the `volumes/html` directory.
159+
And also will start a HTTP server and you can access the documentation at `http://localhost:8000`.
160+
161+
4. To stop the server, press `Ctrl+C` in the terminal.
162+
163+
164+
.. _CC BY 3.0: https://creativecommons.org/licenses/by/3.0/deed.en_US
165+
.. _`Xcode command line tools`: https://stackoverflow.com/questions/9329243/xcode-install-command-line-tools
166+
167+
This README was based on the `Nextcloud documentation <https://github.com/nextcloud/documentation/blob/master/README.rst>`_.

‎docker-compose.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ services:
1212
nginx:
1313
image: nginx:alpine
1414
ports:
15-
- "8080:80"
15+
- "8000:80"
1616
volumes:
1717
- ./volumes/html:/usr/share/nginx/html
1818
- .docker/nginx/nginx.conf:/etc/nginx/conf.d/nginx.conf

‎style_guide.rst‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
=============================
2+
LibreSign manuals style guide
3+
=============================
4+
5+
*This is a work in progress*
6+
7+
See the `Documentation README <https://github.com/LibreSign/documentation/blob/main/README.rst>`_ for information on setting up your documentation build environment
8+
9+
See `reStructuredText Primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ for a complete
10+
Sphinx/RST markup reference.
11+
12+
This is the official style guide for the LibreSign Administration and User
13+
manuals. Please follow these conventions for consistency, and easier
14+
proofreading and copyediting.
15+
16+
When you are writing your text, make it as literal and specific as possible. Put
17+
yourself in the place of the person who is using LibreSign and looking for
18+
instructions on performing a task. Don't make them guess, but spell
19+
out every step in order, and tell exactly what buttons to click or what form
20+
fields to fill out. Give complete information; for example, when making an OCC
21+
configuration change, specify the exact command to run, with the exact
22+
parameters, and the exact user to run it as. When you are describing
23+
features of a GUI administration form use the exact literal names of buttons,
24+
form fields, and menus in English. Specify if menus are dropdown, right-click,
25+
left-click, or mouseover.
26+
27+
Page filenames
28+
--------------
29+
30+
Use lowercase filenames with underscores, for example file_name_config.rst.
31+
32+
Page titles and headings
33+
------------------------
34+
35+
There are many ways to markup headings and subheadings. This is the official
36+
LibreSign way. Use sentence case. Three levels is enough; if you find that you want more,
37+
then re-think the organization of your text::
38+
39+
==============
40+
Page title, h1
41+
==============
42+
43+
Subhead, h2
44+
-----------
45+
46+
Subhead, h3
47+
^^^^^^^^^^^
48+
49+
This is how they render:
50+
51+
==============
52+
Page title, h1
53+
==============
54+
55+
Subhead, h2
56+
-----------
57+
58+
Subhead, h3
59+
^^^^^^^^^^^
60+
61+
Labels and code
62+
---------------
63+
64+
Elements in a GUI configuration form are in bold, and should be described as
65+
literally as possible, so that your description matches what your reader sees
66+
on the screen. For example, on the User listing page describe the various
67+
elements like these examples::
68+
69+
**Username** field
70+
**Password** field
71+
**Groups** dropdown menu
72+
**Create** button
73+
**Full Name** field
74+
**Quota** dropdown menu
75+
76+
This is how they render:
77+
78+
**Username** field
79+
80+
**Password** field
81+
82+
**Groups** dropdown menu
83+
84+
**Create** button
85+
86+
**Full Name** field
87+
88+
**Quota** dropdown menu
89+
90+
.. figure:: users-config.png
91+
:alt: User listings and administration page.
92+
93+
*Figure 1: The file listing and administration page.*
94+
95+
Use double-backticks for inline code and command examples::
96+
97+
``sudo -E -u www-data php occ libresign:configure:check --help``
98+
``libresign:uninstall --jsignpdf``
99+
100+
This is how they render:
101+
102+
``sudo -E -u www-data php occ libresign:configure:check --help``
103+
104+
``libresign:uninstall --jsignpdf``
105+
106+
When you are giving hyperlinks as examples, use double-backticks rather than
107+
creating a live hyperlink::
108+
109+
``https://example.coop``
110+
111+
Images
112+
------
113+
114+
Use lowercase with hyphens for image names, for example image-name.png.
115+
116+
Images should be in .png format. Keep your screenshots focused on the items you
117+
are describing. When you need an image of something large like a configuration
118+
form on the LibreSign admin page, narrow your Web browser to fold the fields
119+
into a smaller space, because a long skinny graphic is not very readable. Think
120+
square.
121+
122+
Both images and figures must have brief and descriptive alt tags and all
123+
figures must have captions with figure numbers. Sphinx RST markup does not
124+
have a tag for figure numbers, so you must
125+
use the caption element. You may use simple numbering like "Figure 1, Figure 2",
126+
or add a caption. Captions must follow a blank line and be italicized, like this example::
127+
128+
.. figure:: images/users-config.png
129+
:alt: User listings and administration page.
130+
131+
*Figure 1: The file listing and administration page.*
132+
133+
Images must go into a sub-directory of the directory containing your manual
134+
page. Currently the manuals have both a single master images directory, and
135+
image directories local to each chapter. A single master images directory is
136+
difficult to maintain and inevitably becomes cluttered with obsolete images. Eventually
137+
the single master directories will be gone.
138+
139+
Example URL
140+
-----------
141+
142+
Use ``https://example.coop`` in your examples where you want to include an URL.
143+
144+
This style_guide was based on the `Nextcloud documentation <https://github.com/nextcloud/documentation/blob/master/style_guide.rst>`_.

0 commit comments

Comments
 (0)