Skip to content

Commit

Permalink
Final Clean Up of version 2.0
Browse files Browse the repository at this point in the history
  • Loading branch information
KinoxKlark committed Apr 18, 2023
1 parent 2ecc5a1 commit b9cb9f2
Show file tree
Hide file tree
Showing 3 changed files with 45 additions and 21 deletions.
43 changes: 31 additions & 12 deletions HACKING.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
# Development tips
We have tried hard to make the process of bootstrapping this project as simple as possible.

In order to build and install the project locally, make sure you have created and activated a virtual environment using `virtualenv` or `python -m venv` (for newer Python releases). Then you can just run:
In order to build and install the project locally, make sure you have created and activated
a virtual environment using `virtualenv` or `python -m venv` (for newer Python releases).
Then you can just run:

make build

This command will bootstrap the whole environment (pull git submodules, install dev requirements, etc.) and build the project. `make` will automatically install `imgui` in the *development/editable* mode. Then you can run some examples found in the `doc/examples` directory in order to verify if the project is working.
This command will bootstrap the whole environment (pull git submodules, install dev requirements, etc.)
and build the project. `make` will automatically install `imgui` in the *development/editable* mode.
Then you can run some examples found in the `doc/examples` directory in order to verify if the project is working.

You can install requirements manually using files `doc/requirements-***.txt`. E.g., with

Expand All @@ -16,25 +20,38 @@ for help by creating a GitHub issue.

# Function mapping

The `imgui.h` file that provides the interface with the DearImGui lib is fully mapped in `imgui/cimgui.pxd`. We use a mark (``/``) system to estimate how many functionalities are mapped automatically. **Please edit the tick mark properly if you want to map an unmapped function**.
The `imgui.h` file that provides the interface with the DearImGui lib is fully mapped in `imgui/cimgui.pxd`.
We use a mark (``/``) system to estimate how many functionalities are mapped automatically.
**Please edit the tick mark properly if you want to map an unmapped function**.

Functions listed in the `cimgui.pxd` correspond to mappable functions for the supported version of DearImGui. Please refer to the next section for information about version syncing.
Functions listed in the `cimgui.pxd` correspond to mappable functions for the supported version of DearImGui.
Please refer to the next section for information about version syncing.

# Version syncing

> Pyimgui 2.0 uses DearImGui 1.82
We specifically bind pyimgui releases to a specific stable version of DearImGui. Thus, when upgrading to a newer version of DearImGui, some care must be taken.
We specifically bind pyimgui releases to a specific stable version of DearImGui. Thus, when upgrading to a newer
version of DearImGui, some care must be taken.

First, one should update the submodule dependency to point to a specific release tag and not just get the latest commits of the `master` branch.
First, one should update the submodule dependency to point to a specific release tag and not just get the latest
commits of the `master` branch.

Moreover, the `docking` branch should also be modified accordingly, such that each branch points to the correct DearImGui release. (Sync list is given in [https://github.com/pyimgui/pyimgui/issues/259#issuecomment-1039090228](https://github.com/pyimgui/pyimgui/issues/259#issuecomment-1039090228))
Moreover, the `docking` branch should also be modified accordingly, such that each branch points to the correct DearImGui
release. (Sync list is given in [https://github.com/pyimgui/pyimgui/issues/259#issuecomment-1039090228](https://github.com/pyimgui/pyimgui/issues/259#issuecomment-1039090228))

When updating the submodule to a recent release, we must update the `imgui/cimgui.pxd` accordingly. This means that all new functions must be mapped with the ``, all depreciated functions must be indicated as such, and so on. Every flag must be properly added and documented in the `imgui/enums.pxd`, `core.pyx`, and `__init__.py`. Idem for the `internal` subpackage.
When updating the submodule to a recent release, we must update the `imgui/cimgui.pxd` accordingly. This means that
all new functions must be mapped with the ``, all depreciated functions must be indicated as such, and so on.
Every flag must be properly added and documented in the `imgui/enums.pxd`, `core.pyx`, and `__init__.py`. Idem for
the `internal` subpackage.

> The easiest way to proceed with updates that skip several releases is to do them one by one. E.g., for going from 1.82 to 1.87, I would suggest taking each release note from DearImGui and upgrading to 1.83 first. And then, when it is fully done, update to 1.84. And so on. At each step, ensure that `cimgui.pxd` is updated and that all enums are properly added. I would also use a file diff software to check the old `imgui.h` with the new one.
> The easiest way to proceed with updates that skip several releases is to do them one by one. E.g., for going from 1.82 to 1.87,
I would suggest taking each release note from DearImGui and upgrading to 1.83 first. And then, when it is fully done,
update to 1.84. And so on. At each step, ensure that `cimgui.pxd` is updated and that all enums are properly added. I would
also use a file diff software to check the old `imgui.h` with the new one.

Since the process is very time-consuming, please refrain from taking the initiative of upgrading DearImGui before asking via an issue. We may have specific plans that you are not informed of.
Since the process is very time-consuming, please refrain from taking the initiative of upgrading DearImGui before asking via an issue.
We may have specific plans that you are not informed of.

# Tests

Expand All @@ -45,7 +62,8 @@ You can run tests with:

py.test

Tests of functionalities are automatically extracted from the `visual-example` part of the docstring documentation of mapped functions. We also have more in-depth tests of specific features in the `tests/` folder.
Tests of functionalities are automatically extracted from the `visual-example` part of the docstring documentation of
mapped functions. We also have more in-depth tests of specific features in the `tests/` folder.

# Documentation

Expand All @@ -61,5 +79,6 @@ Documentation is built using Sphinx. The command used on ReadTheDocs is
python -m sphinx -W --keep-going -T -E -b HTML -d _build/doctrees -D language=en . _build/HTML

**pyimgui** provides documentation with multiple visual examples.
Thanks to custom Sphinx extensions, we are able to render GUI examples off-screen directly from docstring snippets. These examples work also as automated functional tests. Documentation is hosted on
Thanks to custom Sphinx extensions, we are able to render GUI examples off-screen directly from docstring snippets.
These examples work also as automated functional tests. Documentation is hosted on
[pyimgui.readthedocs.io](https://pyimgui.readthedocs.io/en/latest/index.html).
21 changes: 13 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
[![completion](https://img.shields.io/badge/completion-72%25%20%28536%20of%20735%29-blue.svg)](https://github.com/pyimgui/pyimgui)
[![Documentation Status](https://readthedocs.org/projects/pyimgui/badge/?version=dev-version-2.0)](https://pyimgui.readthedocs.io/en/latest/?badge=dev-version-2.0)
[![Build status](https://ci.appveyor.com/api/projects/status/mr97t941p6k4c261/branch/dev/version-2.0?svg=true)](https://ci.appveyor.com/project/KinoxKlark/pyimgui/branch/dev/version-2.0)
<!--[![Coverage Status](https://coveralls.io/repos/github/pyimgui/pyimgui/badge.svg?branch=master)](https://coveralls.io/github/swistakm/pyimgui?branch=master)-->
[![Documentation Status](https://readthedocs.org/projects/pyimgui/badge/?version=latest)](https://pyimgui.readthedocs.io/en/latest/?badge=latest)
[![Build status](https://ci.appveyor.com/api/projects/status/mr97t941p6k4c261/branch/master?svg=true)](https://ci.appveyor.com/project/KinoxKlark/pyimgui/branch/master)

# pyimgui

Python bindings for the amazing
[dear imgui](https://github.com/ocornut/imgui) C++ library - a Bloat-free
Immediate Mode Graphical User Interface.

Documentation: [pyimgui.readthedocs.io](https://pyimgui.readthedocs.io/en/latest/index.html)
Documentation: [pyimgui.readthedocs.io](https://pyimgui.readthedocs.io/en/latest/)

# Installation

Expand All @@ -36,7 +35,7 @@ section of this documentation page.

# Project status

The `imgui` package provides support for the majority of core ImGui widgets and
The `imgui` package provides support for the majority of core DearImGui 1.82 widgets and
functionalities. Some low-level API elements and complex widgets (like plots)
may be missing. We are working hard to provide 100% feature mapping of the core
ImGui library. The *completion badge* shows up-to-date status of that goal.
Expand All @@ -58,8 +57,12 @@ Python versions:
* py37, pp37
* py38, pp38
* py39, pp39
* py310
* py311

__Note:__ We dropped support for py27, py33, py34, and py35 starting from release 2.0. Those were supported until release [1.4.0](https://github.com/pyimgui/pyimgui/releases/tag/1.4.0). Pypy is only supported since release 2.0.
__Note:__ We dropped support for py27, py33, py34, and py35 starting from release 2.0.
Those were supported until release [1.4.0](https://github.com/pyimgui/pyimgui/releases/tag/1.4.0).
Pypy is only supported since release 2.0.

If none of these wheels work in your environment you can install the `imgui`
package by compiling it directly from sdist distribution using one of following
Expand All @@ -72,11 +75,13 @@ commands:
pip install imgui --no-binary imgui

**pyimgui** provides documentation with multiple visual examples.
Thanks to custom Sphinx extensions, we are able to render GUI examples off-screen directly from docstring snippets. These examples work also as automated functional tests. Documentation is hosted on
Thanks to custom Sphinx extensions, we are able to render GUI examples off-screen directly from docstring
snippets. These examples work also as automated functional tests. Documentation is hosted on
[pyimgui.readthedocs.io](https://pyimgui.readthedocs.io/en/latest/index.html).

# Contributing
Contributions are welcomed. If you want to help us by fixing bugs, mapping functions, or adding new features, please feel free to do so and propose a pull request.
Contributions are welcomed. If you want to help us by fixing bugs, mapping functions, or adding new features,
please feel free to do so and propose a pull request.

Development tips and information for developers are given in [HACKING.md](HACKING.md).

2 changes: 1 addition & 1 deletion setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ def backend_extras(*requirements):
long_description=read(README),
long_description_content_type="text/markdown",

url="https://github.com/swistakm/pyimgui",
url="https://github.com/pyimgui/pyimgui",

ext_modules=cythonize(
EXTENSIONS,
Expand Down

0 comments on commit b9cb9f2

Please sign in to comment.