|
1 | 1 | # Contributing to fathon |
2 | 2 |
|
| 3 | +If you have found bugs, or you want to propose a new feature: |
3 | 4 |
|
| 5 | +1. describe the problem and specify the details of your setup (OS, Python version, environment, etc.); |
| 6 | +2. provide a minimal working example that can be easily reproduced and tested; |
| 7 | +3. open an issue with the previous information in the GitHub repository with tag <code>bug</code> or <code>proposed feature</code>. |
4 | 8 |
|
5 | | -## Bug fixes and new features |
| 9 | +PRs are also welcomed. |
6 | 10 |
|
7 | | -If you have found or fixed bugs, or you want to propose or add a new feature, please follow these instructions. |
8 | | - |
9 | | -#### To report a bug: |
10 | | - |
11 | | -1. Describe the problem accurately and specify the details of your setup (OS, Python version, environment, etc.); |
12 | | -2. Provide a minimal working example that can be easily reproduced and tested; |
13 | | -3. Open an issue with the previous information in the Github repository with tag <code>bug</code>. |
14 | | - |
15 | | -#### To fix a bug: |
16 | | - |
17 | | -1. Fork the repository; |
18 | | -2. If the bug involves Cython code and you know Cython: |
19 | | - - Fix the bug; |
20 | | - - Describe the bug, provide a minimal working example that can be easily reproduced and tested to reproduce the bug, and explain how you fixed it; |
21 | | - - Create a pull request including what described in the previous point. |
22 | | -3. If the bug involves Cython code and you do not know Cython: |
23 | | - - Simply report the bug as described in "To report a bug". |
24 | | -4. If the bug involves Python code: |
25 | | - - Follow the same instructions given in point 2. |
26 | | - |
27 | | -#### To propose a new feature: |
28 | | - |
29 | | -1. Open an issue in the Github repository with tag <code>proposed feature</code>; |
30 | | -2. Please try to give a detailed description of the feature, providing references if available. |
31 | | - |
32 | | -#### To add a new feature: |
33 | | - |
34 | | -1. Fork the repository; |
35 | | - |
36 | | -2. If the new feature needs to be written in Cython and you know Cython: |
37 | | - |
38 | | - - Develop the new code; |
39 | | - |
40 | | - - Describe the new feature and provide references if available, provide a minimal working example that can be easily reproduced and tested, and list all the added or modified repository's files; |
41 | | - |
42 | | - - Create a pull request including what described in the previous point. |
43 | | - |
44 | | -3. If the new feature needs to be written in Cython and you do not know Cython: |
45 | | - |
46 | | - - Develop the new code in Python; |
47 | | - - Describe the new feature and provide references if available, provide the new code with information on where to include it, and provide a minimal working example that can be easily reproduced and tested; |
48 | | - - Open an issue with the previous information in the Github repository with tag <code>new feature</code>; |
49 | | - - I will review it and translate the code to Cython. |
50 | | - |
51 | | -4. If the new feature can be written in Python: |
52 | | - |
53 | | - - Follow the same instructions given in point 2. |
54 | | - |
55 | | -#### For any other question regarding the package: |
56 | | - |
57 | | -1. Open an issue as described in "To report a bug", but with tag < code>question</ code>, or write to [email protected]. |
58 | | - |
59 | | - |
60 | | - |
61 | | -## Code formatting |
62 | | - |
63 | | -The current code is formatted using tabs. |
64 | | - |
65 | | -In case you are going to modify `fathon`, please use the same docstring format already present in the source files. |
| 11 | +For any other question, open an issue with tag <code>question</code>. |
66 | 12 |
|
67 | 13 |
|
68 | 14 |
|
69 | 15 | ## Documentation |
70 | 16 |
|
71 | | -Documentation is written in [reStructuredText](http://docutils.sourceforge.net/rst.html), built with <code>sphinx</code> and placed in the <code>docs</code> folder. If you have contributed, please update also the documentation. |
| 17 | +Documentation is written in [reStructuredText](http://docutils.sourceforge.net/rst.html), built with <code>sphinx</code> and placed in the <code>docs</code> folder. |
| 18 | + |
| 19 | +The script <code>docs_gen.sh</code> generates `.py` files with only docstrings, since `sphinx` does not support Cython. |
72 | 20 |
|
73 | | -- Add or modify the function/class in the corresponding <code>.rst</code> file in the folder <code>fun_class</code>, and follow the same naming convention if a new file is needed; |
74 | | -- In case of a new file, add it at the end of <code>index.rst</code>; |
75 | | -- Install <code>sphinx</code> and <code>numpydoc</code>; |
76 | | - - Run <code>docs_gen.sh</code> inside the <code>docs</code> folder (the variable `SPHINXBUILD` in the `Makefile` should be probably changed), and check the result file <code>_build/html/index.html</code>. |
| 21 | +The variable `SPHINXBUILD` in the `Makefile` depends on the particular user's system and should be probably changed. |
77 | 22 |
|
78 | 23 | For any problem with the documentation, open an issue with tag <code>documentation</code>. |
0 commit comments