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
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
.. _contributing:
:github_url:
.. image:: ../_static/scikit-rf-title-flat.svg
:target: ../_static/scikit-rf-title-flat.svg
:height: 100
:align: center
Contributing to scikit-rf
==========================
Sponsoring the Project
----------------------
It is possible to sponsor the maintainers and developers of the scikit-rf package, using the GitHub Sponsor option ("Sponsor this project") visible on the `scikit-rf GitHub page <https://github.com/scikit-rf/scikit-rf>`_.
Sponsoring is one more way to contribute to open source: financially supporting the people who build and maintain it. Funding individuals helps them keep doing important work, expands opportunities to participate, and gives developers the recognition they deserve.
Contributing to the Code
------------------------
.. note:: if you feel that the instructions on this page are too complicated, but you still would like to contribute, do not hesitate to email us on the `scikit-rf mailing list <https://groups.google.com/forum/#!forum/scikit-rf>`_ or join us in the `scikit-rf Slack channel <https://join.slack.com/t/scikit-rf/shared_invite/zt-d82b62wg-0bdSJjZVhHBKf6687V80Jg>`_ or the `scikit-rf Matrix/Element channel <https://app.element.io/#/room/#scikit-rf:matrix.org>`_ to get some help.
**skrf** uses the "Fork + Pull" collaborative development model. If this is new to you, see GitHub's articles on `forking <https://help.github.com/articles/fork-a-repo>`_ and `pull requests <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_.
Basically, you will:
1. `Fork <https://help.github.com/articles/fork-a-repo>`_ the `GitHub scikit-rf repository <https://github.com/scikit-rf/scikit-rf>`_,
2. Make your modifications.
3. Then send a `pull request (PR) <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_ for your additions to be merged into the main scikit-rf repository. Your proposal will be reviewed or discussed and you may receive some comments which only aim to make your contribution as great as possible!
.. tip:: When making your modification locally, you may need to work into a dedicated development environment in order to not interfere with the scikit-rf package that you have `already installed <../tutorials/Installation.html>`_. You can use for example `anaconda environment <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_. In order for the anaconda environment to find your local scikit-rf repo, use the convenient `conda-develop <https://docs.conda.io/projects/conda-build/en/latest/resources/commands/conda-develop.html>`_ command.
Pre-commit
++++++++++
You can use pre-commit_ to automate your code quality checks and perform
automated fixes in **scikit-rf**.
To enable pre-commit on your computer (make sure it is installed first), open a terminal and Navigate to
the :file:`scikit-rf/` directory that contains your clone of scikit-rf's repository, then run:
.. code-block:: bash
pre-commit install
.. note::
Once pre-commit has been installed for a repository, pre-commit will
run every time you try to commit a change. If any pre-commit checks
fail, or if pre-commit changes any files, it will be necessary to
redo `git add` on the changed files and `git commit` once
again.
.. tip::
To commit a change without running pre-commit, use the `-n` or
`--no-verify` flag with git.
Basic git command-line workflow
+++++++++++++++++++++++++++++++
The following is a basic example of the git commands that can be used to contribute to the code.
.. code-block:: sh
# create your own fork of scikit-rf in the GitHub interface, say ME/scikit-rf
# clone your new fork locally, using either:
git clone ME@github.com:ME/scikit-rf.git
# if you have ssh keys setup, or if not:
git clone https://github.com/scikit-rf/scikit-rf.git
# ... make your changes...
# commit changes locally
git commit -a
# push changes to your repo
git push origin
# create a pull request on github.com
Staying Synchronized
++++++++++++++++++++
To keep your local version synchronized (up-to-date) with the scikit-rf repository, `add a "remote" (call it "upstream") <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork>`_. From this remote, you can `"fetch" and "merge" the official scikit-rf repo's changes into your local repo <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork>`_.
.. code-block:: sh
git remote add upstream https://github.com/scikit-rf/scikit-rf.git
# Fetch any new changes from the original repo
git fetch upstream
# Merges any changes fetched into your working files
git merge upstream/master
Tests
+++++
Tests are vital for software reliability and maintainability. Writing tests often require additional effort but saves time in the long run. Tests enable us to quickly discover when we introduce new errors. It is also a way to provide examples of how functions and classes were originally intended to be used.
Before making a Pull Request, we advise contributors to run the tests locally to check if nothing has been broken following their modifications. In addition, we highly recommend providing new tests when adding new features.
The structure of the testing generally follows the conventions of `numpy/scipy <https://github.com/numpy/numpy/blob/master/doc/TESTS.rst>`_. Test cases live in the module, or submodule, which they are testing, and are located in a directory called `tests`. So, the tests of the media module are located at `skrf/media/tests/`.
Tests can be run most easily with `pytest <https://docs.pytest.org/en/latest/index.html>`_.
You probably **don't** want to run the tests for the virtual instruments ``skrf.vi`` with the rest of the tests, so these tests are excluded by default.
To run all the tests (except the virtual instruments)
.. code-block:: sh
cd scikit-rf
# Create environment and install dependencies, needed only once.
python -m venv .venv
pip install -e .[test,visa,netw,xlsx,plot,docs,testspice] --compile
# Activate Environment, needed for all following steps.
# on Linux Systems
. .venv/bin/activate
# on Windows
.\.venv\Scripts\activate
pytest
To run all tests *and* all tutorials and example notebooks in your current environment (recommended before making a pull request):
.. code-block:: sh
pytest --nbval-lax
If you want to test a single file or directory, you need to override the default pytest configuration and indicate the test path. For example, to run only the tests associated with the Network object (-v to increase the verbosity):
.. code-block:: sh
pytest -v -c "" skrf/tests/test_network.py
It is also possible to select some particular tests using the regex option (-k):
.. code-block:: sh
pytest -v -c "" skrf/calibration/tests/test_calibration.py -k "test_error_ntwk"
Contributing to the Documentation
----------------------------------
Examples and Tutorials
++++++++++++++++++++++
Usage examples of scikit-rf are welcomed, especially when adding new features. We are using `Jupyter Notebooks <https://jupyter.org/>`_ to write the examples and the tutorials, which are located in the ``scikit-rf/docs/source/examples/`` and ``doc/source/examples`` directories. These notebooks are then converted into webpages with the sphinx extension called `nbsphinx <http://nbsphinx.readthedocs.io/>`_.
The docs are automatically built and `served by readthedocs <https://scikit-rf.readthedocs.io/en/latest/>`_ when a Pull Request is accepted. The Python package requirements to build the docs are kept in ``scikit-rf/pyproject.toml``.
.. important:: Before pushing to your repo and making a pull request, at a minimum you will need to clear the notebook outputs using the "Clear All Output" command in the notebook (or install `nbstripout <https://pypi.python.org/pypi/nbstripout>`_ so that the output is not tracked in git (or the repo size would grow infinitely).
Reference (API) or static documentation
+++++++++++++++++++++++++++++++++++++++
The documentation source files can be found in ``doc/source/``.
The reference documentation for the functions, classes, and submodules are documented in docstrings following the conventions put forth by `Numpy/Scipy docstring format <https://numpydoc.readthedocs.io/en/latest/format.html>`_. The documentation as a whole is generated using sphinx, and written using reStructed (.rst) Text.
.. tip:: If you want to write some .rst file yourself, please use an RST format editor and checker (ex: `<https://livesphinx.herokuapp.com/>`_), as Sphinx is (very) picky with the syntax...
Building the documentation locally
++++++++++++++++++++++++++++++++++
Before making a pull request concerning the documentation, it is a good idea to test locally if your changes lead to the desired HTML output (sometimes some problems can arise during the conversion to HTML). The documentation is built by the following commands:
.. code-block:: sh
# be sure to be in the scikit-rf/doc directory
make html
The built docs then reside in ``doc/build/html``.
Join the **scikit-rf** team!
----------------------------
Do you like using scikit-rf? `Merchandise is available for you to express your love <https://scikit-rf.org/merch.html>`_.
.. image:: https://raw.githubusercontent.com/scikit-rf/scikit-rf/master/logo/skrfshirtwhite.png
:height: 400
:align: center
|
