Merge pull request #125 from pop-os/fullcolor-improvements-tooling

Tooling Improvements for Fullcolor Icons

CONTRIBUTING

@@ -0,0 +1,17 @@
+## Contributions
+
+We happily consider all pull requests sent our way. When submitting a PR, be sure to abide by our [Code of Conduct](https://github.com/pop-os/code-of-conduct), as submissions in violation will be rejected.
+
+To improve the quality of your submission and increase the chances of acceptance, please consider the following guidelines:
+
+* Ensure that your contribution is of a generally finished quality. PRs and contributions requiring further development by the Pop_OS team may not be accepted.
+
+* Follow existing code and design style where possible. Submissions which don't follow our code or design style may require changes to be accepted. Ensure that icons follow our design language and generally "fit in" with the other Pop Icons. When in doubt, mark your PR as a draft and request assistance from a Pop Icons maintainer.
+
+* Ensure that your changes to icons/cursors follow our in-place development practices. Submissions which add/remove/rename icons within the [`Pop`](./Pop) folder without corresponding changes in the [`src`](./src) folder _will_ not be accepted. 
+
+* Ensure that your icons are rendered out before submitting. Un-render changes will not be visible in the installed theme.
+
+* Consider doing a full-render of the theme before you submit a PR (`./master-render.py -c`). This will erase any existing output files and ensure the theme is in a good, maintainable state and that your changes have been applied in a way which ensures that they will be carried over in the future. _Contributions where running `./master-render.py -c` creates a diff verses the git `HEAD` commit will not be accepted!_ Performing this step prior to submitting your PR will catch many of the above problems before they appear.
+
+These guidelines are important to ensuring the Pop Icons remain maintainable in the future! 

README.md

@@ -1,7 +1,7 @@
 Pop_Icons
 ================
 
-Pop_Icons is the icon theme for Pop!_OS. It uses a semi-flat design with raised 3D motifs to help give depth to icons. 
+Pop_Icons are the standard icons for Pop!_OS. It uses a semi-flat design with raised 3D motifs to help give depth to icons. Included in the theme are flat symbolic (single-color) icons as well as full-color stylized icons.
 
 Pop_Icons take inspiration from the Adwaita GNOME Icons. 
 
@@ -35,7 +35,7 @@ meson build
 sudo ninja -C "build" install
 ```
 
-By default it installs to `/usr/`, but you can specify a different directory with a prefix like `/usr/local` or `$HOME/.local`, for example:
+By default the theme installs to `/usr/`, but you can specify a different directory with a prefix like `/usr/local` or `$HOME/.local`, for example:
 
 ```sh
 meson -Dprefix=$HOME/.local build
@@ -44,7 +44,7 @@ ninja -C "build" install
 
 After which you should be able to pick Pop as your icon or cursor theme in GNOME Tweaks, or you can set either from a terminal with:
 
-```bash
+```sh
 # set the icon theme
 gsettings set org.gnome.desktop.interface icon-theme "Pop"
 # or the cursor theme
@@ -55,13 +55,13 @@ gsettings set org.gnome.desktop.interface cursor-theme "Pop"
 
 To uninstall Pop, simply run the following. (If you installed it without superuser priveleges just omit the  `sudo`.)
 
-```bash
+```sh
 sudo ninja -C "build" uninstall
 ```
 
 Once uninstalled you can reset your icon and cursor theme to the default setting by running the following.
 
-```bash
+```sh
 # reset icon theme to default
 gsettings reset org.gnome.desktop.interface icon-theme
 # reset cursor theme to default
@@ -70,8 +70,92 @@ gsettings reset org.gnome.desktop.interface cursor-theme
 
 ## Modifying the theme
 
-For information on modifications and contributing to the theme, see the 
-README.md in the `src` folder.
+Pop uses the meson build system, and can be built using:
+
+```sh
+meson build
+ninja -C build install
+```
+
+Icons and cursors are shipped pre-rendered in order to save time in the event of modifications to the theme as well as reducing build-load on the Pop_OS build servers. Most modifications are rendered using [`./master-render.py`](master-render.py). For making/rendering modifications:
+
+### General Rendering
+The `./master-render.py` script takes care of rendering each different type of file in the theme. Running it by default will render any missing icon files and any updated full-color icons. You can render specific parts of the theme by using the following flags:
+
+```
+  -a, --all        Render all items (Default)
+  -f, --fullcolor  Render fullcolor icons
+  -s, --symbolics  Render Symbolic Icons
+  -x, --cursors    Render Cursors
+  -l, --links      Generate Theme Symlinks
+  -m, --metadata   Generate Metadata
+```
+
+Using the `-c, --clean` option will erase the currently rendered/generated files in the specified, rendering context, which is helpful in the event a source-file is not rendering when it should be. Using it will re-render all files in the specified context, which can take a long time, so use with care. Using the `-c` flag with `-a, --all` or without another context **will erase all files in the theme and require re-rendering all of them**, so be extra careful. 
+
+Multiple contexts can be combined to render/clean multiple context in one pass, except that any contexts other than `-a, --all` will disable `--all` so keep that in mind.
+
+##### Rendering Dependencies
+The following packages are required to render all of the files within the theme:
+```
+python # Running main, full-color, and cursor render scripts
+ruby # Running symbolic icons render script
+bash # Running symlink script
+inkscape # Renders source files to output
+python3-pil # Renders cursors
+x11-apps # Rendering cursors
+```
+
+Additionally, the following are optional, but will improve the output of the rendering:
+```
+scour # Cleaning up unused definitions from full-color/symbolic SVGs
+svgo # Optimizing full-color and symbolic SVGs
+symlinks # Remove empty symlinks
+```
+
+
+### Full-color icons
+
+The full-color icons are stored within the `src/fullcolor` folder, and are organized into subdirectories for each category of icon. After making a modification to a source icon, the changes will automatically be rendered into the required icon files by `./master-render.py`; if the script is not rendering your icon, double-check that the file timestamp has been updated and that the source file follows the related formatting requirements in [`src/fullcolor/README.md`](src/fullcolor/README.md). 
+
+### Symbolic Icons
+
+The symbolic/single-color icons are stored within the `src/scalable/source-symbolic.svg` file. The file has separate layer for each different category of icon within the theme. Ensure when you modify the file, that your icon is located within the correct layer for it to end up in the correct output directory. 
+
+Symbolic icons require that you remove the corresponding output icon from the `Pop/scalable` folder in order for the `master-render.py` script to re-render. The reason for this is that because there is only a single symbolic source-file, we can't re-render a single icon automatically. If you prefer to let the icons re-render automatically and don't mind waiting for all of the symbolics to render, you can do so using `./master-render.py -cls`
+
+Additional information about the symbolic icons can be found in [`src/scalable/README.md`](src/scalable/README.md)
+
+### Cursors
+
+Cursors are stored in the `src/cursors` directory. Because cursors are somewhat complicated/difficult to render as they are often animated, and because they use a single source file, they need to be re-rendered each time using `./master-render.py -cx`. You can also manually delete the `Pop/cursors` directory. Additional information about rendering the cursors is found in [`src/cursors/README.md`](src/cursors/README.md)
+
+### Symbolic Links
+
+Pop_Icons uses symbolic links to save on disk space and match a larger number of icon names without needing as many unique icons. 
+
+Symbolic link definitions are separated out into `fullcolor` for the full-color icons, and `scalable` for the symbolic icons. Each directory contains a `.list` file for each icon category. Each line in a `.list` file defines exactly one output symlink. The format for each line is `link-target link-name` similar to the `ln` command. For more information regarding symlinks, see the [`src/symlinks/README.md`](src/symlinks/README.md) file.
+
+### Metadata
+
+Currently theme metadata is stored in the main folder within [`index.theme.in`](index.theme.in) and [`cursor.theme.in`](cursor.theme.in). When the output files of these is generated, these are copied directly into the output folder without modification; automatic generation is a planned feature for a later release. In the meantime, modify these files directly and use `./master-render.py` to copy them to the correct locations. 
+
+
+## Pull Requests
+
+We happily consider all pull requests sent our way. When submitting a PR, be sure to abide by our [Code of Conduct](https://github.com/pop-os/code-of-conduct), as submissions in violation will be rejected.
+
+To improve the quality of your submission and increase the chances of acceptance, please consider the following guidelines:
+
+* Ensure that your contribution is of a generally finished quality. PRs and contributions requiring further development by the Pop_OS team may not be accepted.
+
+* Follow existing code and design style where possible. Submissions which don't follow our code or design style may require changes to be accepted. Ensure that icons follow our design language and generally "fit in" with the other Pop Icons. When in doubt, mark your PR as a draft and request assistance from a Pop Icons maintainer.
+
+* Ensure that your changes to icons/cursors follow our in-place development practices. Submissions which add/remove/rename icons within the [`Pop`](./Pop) folder without corresponding changes in the [`src`](./src) folder _will_ not be accepted. 
+
+* Ensure that your icons are rendered out before submitting. Un-render changes will not be visible in the installed theme.
+
+* Consider doing a full-render of the theme before you submit a PR (`./master-render.py -c`). This will erase any existing output files and ensure the theme is in a good, maintainable state and that your changes have been applied in a way which ensures that they will be carried over in the future. _Contributions where running `./master-render.py -c` creates a diff verses the git `HEAD` commit will not be accepted!_ Performing this step prior to submitting your PR will catch many of the above problems before they appear.
 
 ## Missing Icons & Requests
 
@@ -84,4 +168,4 @@ Note: Pop does not supply icons for third-party applications, only those which c
 
 ## Donate & Support
 
-Pop_Icons use Sam Hewitt's Paper icons as an architectural base, although the icon artwork is new. If you would like to support development by making a donation you can do so [here](https://snwh.org/donate) or by becoming a supporter on [Patreon](http://patreon.com/snwh/) or [Liberapay](http://liberapay.com/snwh/). 😊
+Pop_Icons use Sam Hewitt's Paper icons as an architectural base, although the icon artwork is new. If you would like to support development by making a donation you can do so [here](https://snwh.org/donate) or by becoming a supporter on [Patreon](http://patreon.com/snwh/) or [Liberapay](http://liberapay.com/snwh/). 

master-render.py

@@ -42,11 +42,11 @@
 
 
 ## Rendering Functions
-def render_bitmaps() -> None:
+def render_fullcolor() -> None:
     print('  -- Rendering bitmap icons...')
-    os.chdir(SRCDIR / 'bitmaps')
+    os.chdir(SRCDIR / 'fullcolor')
     try:
-        subprocess.run('./render-bitmaps.py', check=True)
+        subprocess.run('./render-fullcolor.py', check=True)
     except subprocess.CalledProcessError:
         print('Failed to render fullcolor icons. See output above.')
         sys.exit(1)
@@ -90,7 +90,7 @@ def render_cursors() -> None:
         return
     shutil.copytree(template_dir, output_dir)
 
-    print('    -- Rendering cursor bitmaps')
+    print('    -- Rendering cursor fullcolor')
     subprocess.run(['./render-cursors.py', '-n 0', 'source-cursors.svg'])
 
     print('    -- Generatig cursor files')
@@ -105,7 +105,7 @@ def install_metadata() -> None:
 
 
 ## Artifact Cleanup/Removal Functions
-def clean_bitmaps() -> None:
+def clean_fullcolor() -> None:
     print('  -- Removing Fullcolor Icons')
     for size in SIZES:
         size_dir = THEMEDIR / size
@@ -149,17 +149,17 @@ def clean_dirs(**kwargs) -> None:
 
     if kwargs['everything']:
         print('  -- Performing Full Cleanup')
-        clean_bitmaps()
+        clean_fullcolor()
         clean_symbolics()
         clean_cursors()
         clean_metadata()
         return
 
     # Cleanup Fullcolors
-    if kwargs['bitmaps']:
-        clean_bitmaps()
+    if kwargs['fullcolor']:
+        clean_fullcolor()
     else:
-        print('  ** Skipping removing bitmaps')
+        print('  ** Skipping removing fullcolor')
 
     # Cleanup Symbolics
     if kwargs['symbolics']:
@@ -184,7 +184,7 @@ def do_render(args) -> None:
     if args.clean:
         clean_dirs(
             everything=args.all,
-            bitmaps=args.bitmaps,
+            fullcolor=args.fullcolor,
             symbolics=args.symbolics,
             cursors=args.cursors,
             metadata=args.metadata
@@ -193,15 +193,15 @@ def do_render(args) -> None:
     print('\n--Rendering icons')
 
     if args.all:
-        render_bitmaps()
+        render_fullcolor()
         render_symbolics()
         render_cursors()
         generate_symlinks()
         install_metadata()
         return
 
-    if args.bitmaps:
-        render_bitmaps()
+    if args.fullcolor:
+        render_fullcolor()
     if args.symbolics:
         render_symbolics()
     if args.cursors:
@@ -227,10 +227,10 @@ def do_render(args) -> None:
     help='Render all items (Default)'
 )
 parser.add_argument(
-    '-b',
-    '--bitmaps',
+    '-f',
+    '--fullcolor',
     action='store_true',
-    help='Render bitmap (fullcolor) icons'
+    help='Render fullcolor icons'
 )
 parser.add_argument(
     '-s',
@@ -259,7 +259,7 @@ def do_render(args) -> None:
 
 args = parser.parse_args()
 
-if not True in (args.bitmaps,
+if not True in (args.fullcolor,
                 args.symbolics,
                 args.cursors,
                 args.links,

src/cursors/README.md

@@ -1,19 +1,21 @@
 ## Cursor Theme Source
 
-- Do not edit cursor assets directly (i.e. those in the "Yaru" folder)! 
+- Do not edit cursor assets directly (i.e. those in the "Pop" folder)! 
 - To modify the cursors, edit source SVG file found in this directory and render them with the appropriate script.
 - To edit the cursors you will need `inkscape` installed and to build and the render the cursor set you'll need `python-pil` and `x11-apps` installed.
 
 ## Render Scripts
 
 For simplified development, has various scripts to render and build the cursor set are provided:
 
- - [**render-cursors.py**](./render-cursors.py) will render the cursor PNG assets into [bitmaps](./bitmaps) at the appropriate sizes; run by passing the source filename to it: `./render-cursors.py source-cursors.svg`
-Inside the Bitmaps folder you'll find folders containing the rendered `.png` files (24x24, 32x32,...). These must be removed, but the `.in` files are needed for the script to run.
+ - [`master-render.py`](../../master-render.py) will render any missing assets in the entire theme. To re-render just cursors, use `./master-render.py -cx`
 
- - [**x11-make.sh**](./x11-make.sh) builds the cursor assets into a Xcursor set and renders them to `/icons/Yaru/cursors/`. These files have no extension.
+ - [`render-cursors.py`](./render-cursors.py) will render the cursor PNG assets into [bitmaps](./bitmaps) at the appropriate sizes; run by passing the source filename to it: `./render-cursors.py source-cursors.svg`
+Inside the Bitmaps folder you'll find folders containing the rendered `.png` files (24x24, 32x32,...). These must be removed, but the `.in` files are needed for the script to run. 
+
+ - [`x11-make.sh`](./x11-make.sh) builds the cursor assets into a Xcursor set and renders them to `/icons/Yaru/cursors/`. These files have no extension.
 
- - [**w32-make.sh**](./w32-make.sh) builds the cursor assets into a Windows cursor set and renders them to `/icons/Yaru/cursors/`. These files have the `.cur`extension.
+ - [`w32-make.sh`](./w32-make.sh) builds the cursor assets into a Windows cursor set and renders them to `/icons/Yaru/cursors/`. These files have the `.cur`extension.
 
 ## Cursor SVG source
 

src/bitmaps/README.md → src/fullcolor/README.md

@@ -8,11 +8,12 @@
     - Do this for each size of icon. This is crucial to rendering the icons without having redundant data.
     - If the final rendered icons are blank, double-check that the correct object is named. 
 
-**[render-bitmaps.py](./render-bitmaps.py) - the render script**
- - This script will render PNG icons, provided there are source changes, in both @1x and @2x (HiDPi) resolutions from the source files.
+**[render-fullcolor.py](./render-bitmaps.py) - the render script**
+ - This script will render SVG icons, provided the source file has been modified. Icons are rendered as SVG so they correctly scale to larger scale factors automatically.
  - You can render a single icon by passing the icon name to this script: `./render-bitmaps.rb <icon-name>`
 
 **[Template.svg](./Template.svg) - a blank icon template**
- - a blank template file for the fullcolor Paper icons (every icon follows this template.)
- - the template has as _Baseplate_ layer which will contain the necessary metadata for rendering an icon. (hidden by default)
- - You **must** change the `context` and `icon-name` labels on the _Baseplate_ for an icon to render properly (also hide the layer)
+ - A blank template file for the fullcolor Pop icons (every icon follows this template.)
+ - The template has as _Baseplate_ layer which will contain the necessary metadata for rendering an icon. (hidden by default)
+ - There is also a _Margins_ layer which gives some example margins/sizes for icons following general aspect ratios. Try to design icons following these aspect ratios as a start, and adapt where required. The margins are setup to give each icon a consistent general apparent size in the grid of all icons.
+ - You **must** change the `context` and `icon-name` labels on the _Baseplate_ for an icon to render properly (also hide the layer). Also, be sure to group each icon into a single object. Set the name for this object using the format {icon-name}-{size} (e.g. edit-delete-64)