Merge commit 'a743ad9496701894406c0d7ded6a44fcecd4219e' as 'deps/QDark'
This commit is contained in:
391
deps/QDark/CONTRIBUTING.rst
vendored
Normal file
391
deps/QDark/CONTRIBUTING.rst
vendored
Normal file
@ -0,0 +1,391 @@
|
||||
Contributing
|
||||
============
|
||||
|
||||
This file describes a path to contribute to this project. Check out our
|
||||
`CODE OF CONDUCT <./CODE_OF_CONDUCT.rst>`__.
|
||||
|
||||
Bug Reports and Feature Requests
|
||||
--------------------------------
|
||||
|
||||
If you have encountered a problem with QDarkStyle or have an idea for a
|
||||
new feature, please submit it to the `issue
|
||||
tracker <https://github.com/ColinDuquesnoy/QDarkStyleSheet/issues>`__.
|
||||
|
||||
Contributing to QDarkStyle
|
||||
--------------------------
|
||||
|
||||
The recommended way for new contributors to submit code to QDarkStyle is
|
||||
to fork the repository on GitHub and then submit a pull request after
|
||||
committing the changes. The pull request will then need to be approved
|
||||
by one of the manteiners before it is merged into the main repository.
|
||||
|
||||
- Check for open issues or open a fresh issue to start a discussion
|
||||
around a feature idea or a bug.
|
||||
|
||||
- Fork `the
|
||||
repository <https://github.com/ColinDuquesnoy/QDarkStyleSheet>`__ on
|
||||
GitHub to start making your changes to the master branch.
|
||||
|
||||
- Write a test which shows that the bug was fixed or that the feature
|
||||
works as expected if its a function, or create a screenshot if you
|
||||
are changing the stylesheet evidencing the changes.
|
||||
|
||||
- Send a pull request and bug the maintainer until it gets merged and
|
||||
published. Make sure to add yourself to `AUTHORS <./AUTHORS.rst>`__
|
||||
and the change(s) to `CHANGES <./CHANGES.rst>`__.
|
||||
|
||||
Getting Started
|
||||
---------------
|
||||
|
||||
These are the basic steps needed to start developing on QDarkStyle.
|
||||
|
||||
- Create an account on GitHub
|
||||
|
||||
- Fork the main `QDarkStyle
|
||||
repository <https://github.com/ColinDuquesnoy/QDarkStyleSheet>`__
|
||||
using the GitHub interface.
|
||||
|
||||
- Clone the forked repository to your machine
|
||||
|
||||
.. code:: bash
|
||||
|
||||
git clone https://github.com/USERNAME/qdarkstyle
|
||||
cd qdarkstyle
|
||||
|
||||
- Checkout the appropriate branch
|
||||
|
||||
.. code:: bash
|
||||
|
||||
git checkout master
|
||||
|
||||
- Setup a virtual environment (not essential, but highly recommended)
|
||||
|
||||
.. code:: bash
|
||||
|
||||
virtualenv ~/.venv
|
||||
. ~/.venv/bin/activate
|
||||
pip install -e .
|
||||
|
||||
- Create a new working branch. Choose any name you like
|
||||
|
||||
.. code:: bash
|
||||
|
||||
git checkout -b feature-xyz
|
||||
|
||||
- Hands on
|
||||
|
||||
For tips on working with the code, see the Code Guide.
|
||||
|
||||
- Test, test, test
|
||||
|
||||
Testing is best done through ``tox``, which provides a number of
|
||||
targets and allows testing against multiple different Python
|
||||
environments:
|
||||
|
||||
- Add you and your changes
|
||||
|
||||
Please add a list item to `CHANGES <./CHANGES.rst>`__ if the fix or
|
||||
feature is not trivial (small doc updates, typo fixes). Please add
|
||||
you as an author to `AUTHORS <./AUTHORS.rst>`__.
|
||||
|
||||
- Add files to commit
|
||||
|
||||
Add files that are part of your changes, remember that each commit
|
||||
must represent a small but functional change. Remember to add
|
||||
CHANGES.rst and AUTHORS.rst too. To add all files changed do:
|
||||
|
||||
::
|
||||
|
||||
```bash
|
||||
git add .
|
||||
```
|
||||
|
||||
- Commiting changes.
|
||||
|
||||
GitHub recognizes certain phrases that can be used to automatically
|
||||
update the issue tracker, so you can commit like this:
|
||||
|
||||
::
|
||||
|
||||
```bash
|
||||
git commit -m "Add useful new feature that does this, close #42"
|
||||
```
|
||||
|
||||
```bash
|
||||
git commit -m "Fix returning problem for get_style(), fix #78"
|
||||
```
|
||||
|
||||
- Push changes in the branch to your forked repository on GitHub.
|
||||
|
||||
::
|
||||
|
||||
```bash
|
||||
git push origin feature-xyz
|
||||
```
|
||||
|
||||
- Submit a pull request (PR).
|
||||
|
||||
Do it from your branch to the respective branch using the `GitHub
|
||||
PR <https://github.com/ColinDuquesnoy/QDarkStyleSheet/pulls>`__
|
||||
interface.
|
||||
|
||||
- Wait for a mainteiner to review your changes.
|
||||
|
||||
Logging
|
||||
-------
|
||||
|
||||
Inside modules we provided a logging that should be used to inform the
|
||||
user. Please, follow the levels bellow.
|
||||
|
||||
- debug: for debug information, high detailed one, directed to
|
||||
programers;
|
||||
|
||||
- info: something important for common user to know;
|
||||
|
||||
- warning: something that should not be a big problem or a desicision
|
||||
changed;
|
||||
|
||||
- error: some error, but not capable of stop program;
|
||||
|
||||
- critical: something that could stop the running program.
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
Documentation is the key to keep all information and necessary
|
||||
instructions to others. We use the reStructured text format (rst) for
|
||||
all docs.
|
||||
|
||||
All new functions, classes, files, must be documented with all
|
||||
arguments, returns, exceptions. Whithout this it should not pass the
|
||||
tests.
|
||||
|
||||
The better example is to see the current files to get the style. We are
|
||||
using the Google Format and Sphinx for generating the docs.
|
||||
|
||||
Guide to QDarkStyle
|
||||
-------------------
|
||||
|
||||
Structure of the Example
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Now you can use our example to work on the stylesheet. It has all
|
||||
possible widget provided by Qt - common ones. Feel free to add more to
|
||||
them.
|
||||
|
||||
To simplify the structure, there are separated files in
|
||||
`example.ui <./example/ui/>`__ folder.
|
||||
|
||||
- ``dw_buttons.ui``: all types of buttons;
|
||||
- ``dw_containers_no_tabs.ui``: all types of containers except for
|
||||
tabs;
|
||||
- ``dw_containers_tabs.ui``: all containers tabs;
|
||||
- ``dw_displays.ui``: all types of displays;
|
||||
- ``dw_inputs_fields.ui``: all types of inputs with fields;
|
||||
- ``dw_inputs_no_fields.ui``: all types of inputs without fields;
|
||||
- ``dw_views.ui``: all types of views;
|
||||
- ``dw_widgets.ui``: all types of widgets;
|
||||
- ``mw_menus.ui``: main window with all menus and toolbars.
|
||||
|
||||
*Obs.: ``dw`` stands for dock widget and ``mw`` for main window.*
|
||||
|
||||
The entire example is built at runtime, in
|
||||
`example.py <./example/example.py>`__. To see more information about it,
|
||||
see its documentation.
|
||||
|
||||
Modifying UI Files
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Feel free to modify `ui <./example/ui>`__ files with Qt Designer and
|
||||
recompile UI using `process\_ui.py <./script/process_ui.py>`__ script,
|
||||
inside script folder, using:
|
||||
|
||||
::
|
||||
|
||||
```bash
|
||||
python process_ui.py
|
||||
```
|
||||
|
||||
It will generate all ``_ui.py`` files for PyQt4, PyQt5, PySide, QtPy,
|
||||
PyQtGraph.
|
||||
|
||||
Modifying QSS File
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you are changing the `stylesheet <./qdarkstyle/style.qss>`__, you
|
||||
will need to recompile the QRC files using
|
||||
`process\_qrc.py <./script/process_qrc.py>`__ script, inside script
|
||||
folder.
|
||||
|
||||
::
|
||||
|
||||
```bash
|
||||
python process_qrc.py
|
||||
```
|
||||
|
||||
This generates all ``_rc.py`` files for PyQt4, PyQt5, PySide, QtPy,
|
||||
PyQtGraph.
|
||||
|
||||
Making It Easy
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
To simplify this process for the developer, if you are changing many
|
||||
things, use the script
|
||||
`run\_ui\_css\_edition.py <./script/run_ui_css_edition.py>`__:
|
||||
|
||||
::
|
||||
|
||||
```bash
|
||||
python run_ui_css_edition.py
|
||||
```
|
||||
|
||||
This creates a loop that restarts the application, process ui and css
|
||||
files.
|
||||
|
||||
For more information about those scripts, see their documentation.
|
||||
|
||||
Qt, Stylesheets, Palettes and Icons
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- `Box model <http://doc.qt.io/qt-5/images/stylesheet-boxmodel.png>`__
|
||||
- `Box model with height and
|
||||
width <https://www.tutorialrepublic.com/lib/images/css-box-model.jpg>`__
|
||||
- `Customizing
|
||||
Widgets <http://doc.qt.io/qt-5/stylesheet-customizing.html>`__
|
||||
- `Window
|
||||
structure <http://doc.qt.io/qt-5/images/mainwindowlayout.png>`__
|
||||
- `QMainWindow <http://doc.qt.io/qt-5/qmainwindow.html>`__
|
||||
- `References <http://doc.qt.io/qt-5/stylesheet.html>`__
|
||||
|
||||
Create good palettes with these tools. For example, on paletton, choose
|
||||
three colors from greyish light (foreground), greyish dark (background)
|
||||
and three more colorfull colors (selection). Greyish colors have a litle
|
||||
bit of the main color, so it is nice to change it if you change the main
|
||||
color.
|
||||
|
||||
- `Paletton.com <http://paletton.com/>`__
|
||||
- `Coolors.co <https://coolors.co/>`__
|
||||
|
||||
As a minimal guide to create new icons (svg) images, we list two main
|
||||
sources.
|
||||
|
||||
- `Material <https://material.io/design/iconography/product-icons.html#grid-keyline-shapes>`__
|
||||
- `KDE <https://hig.kde.org/style/icon.html>`__
|
||||
|
||||
Main characteristics of SVG images are:
|
||||
|
||||
- Base size: 32px X 32px;
|
||||
- Border: 2px space, except continuous lines;
|
||||
- Corners and line end's: rounded;
|
||||
- Line: 2px minimum thickness. Complementary thickness using multiples
|
||||
of 2px;
|
||||
- Spacing: 4px when needed;
|
||||
- Color: #ff0000, red for all images - programatically changed;
|
||||
- Keep only structural changes in images, not colors, e.g, states hover
|
||||
and disabled;
|
||||
- Lines and shapes should align with the grid centralized;
|
||||
- Names: from basic form to specific, so they keep grouped. Ex.:
|
||||
arrow\_left, arrow\_up.
|
||||
|
||||
Some example are given below for the horizontal Handle, Minimize, and
|
||||
checked Checkbox.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table style="width:100%">
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<tr>
|
||||
|
||||
::
|
||||
|
||||
<th colspan=3>Examples of icons</th>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</tr>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<tr>
|
||||
|
||||
::
|
||||
|
||||
<td><img src="./images/icon_checkbox_indeterminated.png"/></td>
|
||||
<td><img src="./images/icon_minimize.png"/></td>
|
||||
<td><img src="./images/move.png"/></td>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</tr>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</table>
|
||||
|
||||
Unit Testing and Fix Preview
|
||||
----------------------------
|
||||
|
||||
It is a good practice, if you are writing functions to QDarkStyle or
|
||||
fixing something related to those functions (not style), that you
|
||||
provide a test for it.
|
||||
|
||||
If you are fixing something about style, please, at least, provide an
|
||||
screenshot before and after the fix to comparison. This could be
|
||||
inserted in the issue tracker, as a message. Better than that, use
|
||||
modules provided in test folder to create a GUI test, creating a new
|
||||
file for it.
|
||||
|
||||
Check `test <./test>`__ files to more details. Tests will keep our
|
||||
application stable.
|
||||
|
||||
If You Are a Mantainer, Go Ahead to Production
|
||||
----------------------------------------------
|
||||
|
||||
Of course, until you start these steps, make sure the package have
|
||||
passed all tests and checkers before continue. You must have accoutns to
|
||||
both test and oficial PyPI website below along with be inserted as a
|
||||
maintainer in both.
|
||||
|
||||
1. Install ``twine``
|
||||
|
||||
``pip install twine``
|
||||
|
||||
2. Generate a distribution (code package and wheel)
|
||||
|
||||
``python setup.py sdist bdist_wheel``
|
||||
|
||||
3. Check with ``twine``, which also tests README format for PyPI
|
||||
|
||||
``twine check dist/*``
|
||||
|
||||
4. Try upload in `PyPI test
|
||||
page <https://test.pypi.org/project/QDarkStyle>`__ platform before
|
||||
the oficial
|
||||
|
||||
``twine upload --repository-url https://test.pypi.org/legacy/ dist/*``
|
||||
|
||||
5. Try to install from test
|
||||
|
||||
``pip install --no-deps --index-url https://test.pypi.org/simple/ qdarkstyle``
|
||||
|
||||
6. Then, remove it
|
||||
|
||||
``pip uninstall qdarkstyle -y``
|
||||
|
||||
7. Upload to `PyPI official
|
||||
page <https://pypi.python.org/pypi/QDarkStyle>`__
|
||||
|
||||
``twine upload --repository-url https://upload.pypi.org/legacy/ dist/*``
|
||||
|
||||
8. Try to install from oficial
|
||||
|
||||
``pip install qdarkstyle``
|
||||
|
||||
You can also use the tox environment to produce the release and upload
|
||||
the distribution.
|
||||
|
||||
::
|
||||
|
||||
`tox -e release`
|
||||
Reference in New Issue
Block a user