Skip to content
This repository was archived by the owner on Jul 2, 2024. It is now read-only.

Commit 3857373

Browse files
shorodilovshorodilov
authored
Add contributing guide and code of conduct (#86)
2 parents 186214d + 442b616 commit 3857373

File tree

3 files changed

+370
-1
lines changed

3 files changed

+370
-1
lines changed

‎.github/CODE_OF_CONDUCT.rst‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
Contributor Covenant Code of Conduct
2+
====================================
3+
4+
Our Pledge
5+
----------
6+
7+
In the interest of fostering an open and welcoming environment, we as
8+
contributors and maintainers pledge to making participation in our
9+
project and our community a harassment-free experience for everyone,
10+
regardless of age, body size, disability, ethnicity, gender identity and
11+
expression, level of experience, education, socio-economic status,
12+
nationality, personal appearance, race, religion, or sexual identity and
13+
orientation.
14+
15+
Our Standards
16+
-------------
17+
18+
Examples of behavior that contributes to creating a positive environment
19+
include:
20+
21+
- Using welcoming and inclusive language
22+
- Being respectful of differing viewpoints and experiences
23+
- Gracefully accepting constructive criticism
24+
- Focusing on what is best for the community
25+
- Showing empathy towards other community members
26+
27+
Examples of unacceptable behavior by participants include:
28+
29+
- The use of sexualized language or imagery and unwelcome sexual
30+
attention or advances
31+
- Trolling, insulting/derogatory comments, and personal or political
32+
attacks
33+
- Public or private harassment
34+
- Publishing others’ private information, such as a physical or
35+
electronic address, without explicit permission
36+
- Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
Our Responsibilities
40+
--------------------
41+
42+
Project maintainers are responsible for clarifying the standards of
43+
acceptable behavior and are expected to take appropriate and fair
44+
corrective action in response to any instances of unacceptable behavior.
45+
46+
Project maintainers have the right and responsibility to remove, edit,
47+
or reject comments, commits, code, wiki edits, issues, and other
48+
contributions that are not aligned to this Code of Conduct, or to ban
49+
temporarily or permanently any contributor for other behaviors that they
50+
deem inappropriate, threatening, offensive, or harmful.
51+
52+
Scope
53+
-----
54+
55+
This Code of Conduct applies both within project spaces and in public
56+
spaces when an individual is representing the project or its community.
57+
Examples of representing a project or community include using an
58+
official project e-mail address, posting via an official social media
59+
account, or acting as an appointed representative at an online or
60+
offline event. Representation of a project may be further defined and
61+
clarified by project maintainers.
62+
63+
Enforcement
64+
-----------
65+
66+
Instances of abusive, harassing, or otherwise unacceptable behavior may
67+
be reported by contacting the project team at {{ email }}. All
68+
complaints will be reviewed and investigated and will result in a
69+
response that is deemed necessary and appropriate to the circumstances.
70+
The project team is obligated to maintain confidentiality with regard to
71+
the reporter of an incident. Further details of specific enforcement
72+
policies may be posted separately.
73+
74+
Project maintainers who do not follow or enforce the Code of Conduct in
75+
good faith may face temporary or permanent repercussions as determined
76+
by other members of the project’s leadership.
77+
78+
Attribution
79+
-----------
80+
81+
This Code of Conduct is adapted from the `Contributor
82+
Covenant <https://www.contributor-covenant.org>`__, version 1.4,
83+
available at
84+
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

‎.github/CONTRIBUTING.rst‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
.. _Sphinx: https://www.sphinx-doc.org/
2+
.. _sphinxcontrib-mermaid: https://pypi.org/project/sphinxcontrib-mermaid/
3+
.. _poedit: https://poedit.net/
4+
5+
###############################################################################
6+
CONTRIBUTING GUIDES
7+
###############################################################################
8+
9+
Welcome and thank you for considering contributing to our project! Here we have
10+
an ecosystem of documentation tools, what helps us to deliver valuable
11+
knowledge about Python programming language to the public.
12+
13+
Collaborating with us means delving into this, which this guide will help you
14+
navigate. From the intricacies of Sphinx to the fluidity of Mermaid diagrams,
15+
we aim to provide you with all the insights you need.
16+
17+
Let's dive in!
18+
19+
*******************
20+
Documentation tools
21+
*******************
22+
23+
`Sphinx`_ makes it easy to create intelligent and beautiful documentation.
24+
This is the main documentation generator used on this project. There are also
25+
some 3rd-party dependencies, like ``sphinxcontrib-mermaid`` or
26+
``MyST markdown`` installed, that makes it possible to use some extended
27+
syntax. Just install all project dependencies (including development).
28+
29+
.. code-block:: shell
30+
31+
poetry install --with dev
32+
33+
**requirements.txt** file does not split general and development deps, just do:
34+
35+
.. code-block:: shell
36+
37+
pip install -r requirements.txt
38+
39+
Other useful tools
40+
==================
41+
42+
We found `poedit`_ software very useful for working with translations.
43+
It can be used for documents automatic translation, storing translation
44+
memories, proofreading etc.
45+
46+
********************
47+
Repository structure
48+
********************
49+
50+
::
51+
52+
/
53+
|-- assets/
54+
|-- src/
55+
|-- index.txt
56+
|---- index.txt
57+
|---- <topic>/
58+
59+
**assets** directory contains various static content for the documentation,
60+
like CSS, images etc.
61+
62+
**src** directory is the main documentation source, and it's considered to be
63+
a *content-root*. It means you may refer this directory as ``/`` for the Sphinx
64+
documentation builder.
65+
66+
The **src/index.txt** is the master document. It combines all the content
67+
together. All topics are described in their own "topic" directories, each with
68+
its own *index.txt*. Topic index file is the :abbr:`TOC (Table of Content)` for
69+
the topic, and it should be added to the master TOC.
70+
71+
Submodules
72+
==========
73+
74+
There are two major approaches in the code base organization: monorepo and
75+
multirepo.
76+
77+
This repository uses **hybrid poly-as-mono** approach. It includes several
78+
other repositories as its submodules to glue the content from different repos
79+
together.
80+
81+
Make sure submodules are pulled from the ``devel`` branch.
82+
83+
***************************
84+
Documentation markup syntax
85+
***************************
86+
87+
The documentation build system supports:
88+
89+
- `reStructuredText <https://docutils.sourceforge.io/rst.html>`_
90+
- `MarkDown <https://daringfireball.net/projects/markdown/>`_
91+
- `mermaid <https://mermaid.js.org/>`_
92+
93+
The main documentation syntax is "reST", since it provides more flexibility
94+
while working with docs.
95+
96+
reStructuredText syntax
97+
=======================
98+
99+
Headings
100+
--------
101+
102+
Here we use structure "part > chapter > section > subsection".
103+
104+
::
105+
106+
####
107+
Part
108+
####
109+
110+
*******
111+
Chapter
112+
*******
113+
114+
Section
115+
=======
116+
117+
Subsection
118+
----------
119+
120+
All of these above will be added to :abbr:`TOC (Table of Content)`.
121+
In case you want to avoid this use ``rubric`` directive to mark a heading
122+
without adding it to the TOC.
123+
124+
::
125+
126+
.. rubric:: Rubric heading
127+
128+
And the content goes here.
129+
130+
Mermaid diagrams
131+
----------------
132+
133+
The build system supports ``mermaid`` syntax via ``.. mermaid::`` directive.
134+
This is done using `sphinxcontrib-mermaid`_ extension.
135+
136+
There are two main approaches to include mermaid diagrams to the documentation:
137+
138+
- integrate a file containing the diagram
139+
140+
::
141+
142+
.. mermaid:: /../assets/mermaid/<path>/<file.mmd>
143+
144+
- integrate the mermaid block itself
145+
146+
::
147+
148+
.. mermaid::
149+
150+
flowchart LR
151+
id
152+
153+
MarkDown
154+
========
155+
156+
MarkDown is not the main markup language, but it is supported as well.
157+
158+
Headings
159+
--------
160+
161+
Just place a hash symbol before the heading. The number of hashes controls
162+
the heading's level.
163+
164+
::
165+
166+
# Part
167+
## Chapter
168+
### Section
169+
#### Subsection
170+
171+
Mermaid diagrams
172+
----------------
173+
174+
Mermaid support for MarkDown source is limited with just including mermaid
175+
blocks:
176+
177+
::
178+
179+
```mermaid
180+
flowchart LR
181+
id
182+
```
183+
184+
*********
185+
Branching
186+
*********
187+
188+
Branches explanation
189+
====================
190+
191+
This repo comes with two main branches: ``master`` and ``devel``.
192+
``master`` branch contains some stable releases of the documentation, while
193+
``devel`` aggregates works for the future releases.
194+
195+
Working with topic branch(es)
196+
=============================
197+
198+
We use GitFlow approach on this project. This means you would not commit to
199+
``master`` or ``devel`` branches directly. Instead you are to create a topic
200+
branch to work with.
201+
202+
For example, if you want to describe "Django middleware", you will create
203+
a new branch ``[topic/|feature/]django-middleware``, and you will commit all
204+
your work to this branch.
205+
206+
Once you consider the work is done - just open a pull request from your topic
207+
branch to ``devel``.
208+
209+
**********************
210+
Working with documents
211+
**********************
212+
213+
Do not make changes in **src** directory directly, except changes to "conf.py"
214+
and "index.txt" files. Keep your documents in dedicated topic directories
215+
instead. This project has some predefined topics already, so you can work
216+
inside of an existing topic directory.
217+
218+
How to add new document(s)
219+
==========================
220+
221+
Locate the corresponding topic and create a new text file.
222+
Use ``.txt`` extension for the reStructuredText documents, and ``.md`` for
223+
the Markdown markup. Keep filename meaningful.
224+
225+
To attach the newly created document to the documentation builds, just add
226+
its name to the ``toctree`` directive content in the **index.txt** file
227+
within the appropriate topic directory. Do not add file extension while adding
228+
file to the ``toctree``.
229+
230+
In rare cases, when the new document should not be a part of any toctree, you
231+
are to ``:orphan:`` mark at its begging.
232+
233+
How to add new topic(s)
234+
=======================
235+
236+
Most of the topics are already present in the documents root. However, in case
237+
of need to add a new topic - you are to create a new directory inside of *src*
238+
folder. Create a file called ``index.txt`` within a new directory, and add it
239+
to the master doc (toctree): **src/index.txt**.
240+
241+
How to translate
242+
================
243+
244+
There is a target defined in Makefile to build and/or update translations
245+
called ``locales``. To gather newly added or updated strings and prepare
246+
portable object files, do:
247+
248+
.. code-block:: shell
249+
250+
make locales
251+
252+
This will create/update po files in *src/_locales* directory. Navigate to
253+
the file and perform translations.
254+
255+
Original strings are marked as ``msgid``, and the translated versions are
256+
marked as ``msgstr``.
257+
258+
Using software like `poedit`_ can make the translation process more efficient.
259+
260+
In case, you don't have cmake/make installed on your computer, you may use
261+
the full commands to gather the text, and prepare po file:
262+
263+
.. code-block:: shell
264+
265+
sphinx-build -b gettext src _build/gettext
266+
sphinx-intl -c src/conf.py update -p _build/gettext
267+
268+
Actually, ``make locales`` is the shortcut to the same set of commands.

‎README.rst‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ To do the same using poetry:
4848
.. _poetry: https://python-poetry.org
4949

5050
Building documentation
51-
----------------------
51+
======================
5252

5353
This repository comes with *Makefile*. For now this is the easiest way to do
5454
anything within this source code. There are several targets defined:
@@ -84,3 +84,20 @@ This command is equal to:
8484
make clean
8585
LANGUAGE=en make html
8686
LANGUAGE=uk make html
87+
88+
Building without make
89+
---------------------
90+
91+
``make`` just automates the build process, however in case you don't have it
92+
installed, you can run builds manually:
93+
94+
.. code-block:: shell
95+
96+
sphinx-build -b html -D language=en src _build/html/en
97+
sphinx-build -b html -D language=uk src _build/html/uk
98+
99+
Contributing to the project
100+
===========================
101+
102+
This is an open-source project, so anyone is welcome to contribute to it.
103+
Please see `contributing guide <./.github/CONTRIBUTING.rst>`_ for more details.

0 commit comments

Comments
 (0)