-
Notifications
You must be signed in to change notification settings - Fork 13
/
Copy pathCONTRIBUTING
88 lines (60 loc) · 3.58 KB
/
CONTRIBUTING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
Coding style
------------
The code is written to loosely follow the PEP8 style guide. Single quoted
strings are preferred but double quotes are fine to avoid unsightly escapes.
All non-trivial functions and methods should have a basic docstring.
Parameters do not have to be described.
I have tried to keep the core of the code in opbasm.py. It should be capable
of running standalone without obpasm_lib being present. Any features implemented
in external files should gracefully degrade when they are missing.
Documentation
-------------
The documentation is written in restructured text (rst) using the Sphinx extensions.
To generate new static HTML you need the Sphinx tools installed. The doc/makefile
has an html target for making new pages:
> make html
This generates new files in _build/html. If you're modifying styles or other
non-content related files you will have to manually delete _build because the
makefile doesn't have dependencies on them.
The static html is stored in a gh-pages branch of the repository. You need to create
a fresh clone of the repo and switch to that branch:
> git clone https://github.com/kevinpt/opbasm.git
> git checkout -t origin/gh-pages
Then you can copy the static HTML from the original repo into root of the gh-pages repo.
If you have created this repository as opbasm-html in the same directory as the opbasm
repo you can use the "gh-pages" make target to run the whole process.
> make gh-pages
Once pushed back to the Github server the new HTML will be accessible from the github.io
site.
Translations
------------
Localized translations are implemented with the Python adaptation of GNU
Gettext. In the code, translatable strings are wrapped in the _() function call.
You should write strings so that they translate readily to different grammars.
Avoid composing strings through concatenation and use .format() instead to
permit more flexible word order among the translations.
You will need the xgettext and poedit tools or similar equivalents.
All localization work is done in the opbasm_lib/lang tree. The following
process is needed to start a new language:
1 Extract the latest strings from opbasm.py and pb_update.py into their
.pot template files located in opbasm_lib/lang
> xgettext opbasm.py -o opbasm_lib/lang/opbasm.pot
2 create a new directory in opbasm_lib/lang using the two letter ISO
language code in lower case. Inside this create an LC_MESSAGES
directory.
3 Run the poedit tool and select "File|New from POT/PO file...". Select the
language then select "Catalog|Properties..." and verify that the encoding is
set to UTF-8. You're ready to proceed with creating new translations. There
is a special string "en" that should be translated to the new language
code. This is used by Opbasm to identify the currently active language.
4 Save the translations to opbasm.po or pb_update.po in the LC_MESSAGES
directory. Then select "File|Compile to MO" and save the .mo file in the
same location. Poedit can also be set to automatically generate the .mo file.
5 Verify the new translations work by changing the LANG environment variable
to the value <lang>_<COUNTRY>.utf8. i.e. de_DE.utf8 or zh_CN.utf8.
6 Add all new files to the repository and push them out.
To update an existing translation you skip step 2 and do the following for step 3:
3a Load an existing .po file with "File|Open..."
3b Select "Catalog|Update from POT file..." and update with the new template
created by xgettext.
3c Translate new and modified strings shown in bold text.