v0.4.0 (#33)

* initial

* legend styling

* legend locations

* objects in legend

* comment

* comment

* fix zorder

* store hash instead of image

* keep dir

* add moon

* tick marks

* tick style

* python311

* use python 3.11

* update hashes

* add legend style to docs

* space

* remove shapely step

* better positioning of ecliptic labels

* plot star labels in order of mag

* lint

* specify units

* not needed

* update examples

* add legend style

* update hash

* version

* clarify

* doc string

* doc string

* typo

Author: steveberardi

.github/workflows/release.yml

@@ -10,9 +10,6 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v3
-    - uses: actions/setup-python@v4
-      with:
-        python-version: '3.9'
     - name: Build Docker image - dev
       run: make docker-dev
     - name: Check Lint

.github/workflows/test.yml

@@ -12,9 +12,6 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v3
-    - uses: actions/setup-python@v4
-      with:
-        python-version: '3.9'
     - name: Build Docker image - dev
       run: make docker-dev
     - name: Check Lint

Dockerfile

@@ -1,13 +1,9 @@
-FROM python:3.10.12-bookworm as base
+FROM python:3.11.4-bookworm as base
 
 WORKDIR /starplot
 
 RUN apt-get update -y && apt-get install -y libgeos-dev libgdal-dev
 
-# Install shapely from source to avoid cartopy segfault
-# https://stackoverflow.com/questions/52374356/
-RUN pip install --no-binary :all: shapely==2.0.1
-
 # Install fonts
 # not required, but make the maps look better (especially greek letters)
 RUN mkdir -p /usr/share/fonts/truetype
@@ -16,7 +12,19 @@ RUN install -m644 /tmp/fonts/*.ttf /usr/share/fonts/truetype/
 RUN fc-cache -f
 
 # ---------------------------------------------------------------------
-FROM sberardi/starplot-base as dev
+FROM python:3.10.12-bookworm as base310
+
+WORKDIR /starplot
+
+RUN apt-get update -y && apt-get install -y libgeos-dev libgdal-dev
+
+# MAYBE REQUIRED for Python 3.10.x? TODO: investigate more
+# Install shapely from source to avoid cartopy segfault
+# https://stackoverflow.com/questions/52374356/
+RUN pip install --no-binary :all: shapely==2.0.1
+
+# ---------------------------------------------------------------------
+FROM base as dev
 
 WORKDIR /starplot
 

README.md

@@ -58,10 +58,7 @@ p.export("starchart.png")
 - adjustText
 
 ## Coming Soon
-
-- ⭐ Tycho stars
-- 🌖 Moon
-- 📋 Map legends
+- ⭐ Custom markers
 - 🔭 Scope plots - that will simulate what you'll see through a telescope eyepiece
 - ⚖️ Better auto font-size adjustment
 - ☄️ Better label collision detection and handling

docs/examples.md

@@ -13,7 +13,7 @@ To create a star chart for the sky as seen from [Palomar Mountain](https://en.wi
 {% include 'examples/example_1.py' %}
 ```
 
-The created file should look something like this:
+The created file should look like this:
 
 ![starchart-blue](images/example_1.png)
 
@@ -31,13 +31,13 @@ Building on the first example, you can also plot additional objects and even cus
 
 ## Map of Orion
 
-The following code will create a simple map plot that shows the area around the constellation Orion, including an extra marker for M42 - The Great Orion Nebula:
+The following code will create a simple map plot that shows the area around the constellation Orion, including a legend and an extra marker for M42 - The Great Orion Nebula:
 
 ```python
 {% include 'examples/example_3.py' %}
 ```
 
-The result should look something like this:
+The result should look like this:
 
 ![map-orion](images/example_3.png)
 

docs/images/example_1.png

@@ -1,14 +1,9 @@
 Starplot is available on [PyPI](https://pypi.org/project/starplot/), but it's basically just a thin layer on top of Matplotlib, Skyfield, Cartopy, and others. So, before installing Starplot you'll need a few dependencies. Below are instructions for installing on macOS and Linux.
 
-!!! tip "Docker Base Image Available"
-
-    Installing the base dependencies for Starplot can take awhile (10+ minutes), so I've created a base Docker image that has some of these dependencies compiled already which saves a lot of time. The image is available on [Docker Hub](https://hub.docker.com/r/sberardi/starplot-base).
-
 ## Required Dependencies
 
 - GEOS
 - GDAL
-- Shapely
 
 ## macOS
 
@@ -17,13 +12,7 @@ Starplot is available on [PyPI](https://pypi.org/project/starplot/), but it's ba
 brew install geos gdal
 ```
 
-2. **Install Shapely:**
-```
-pip install --no-binary :all: shapely
-```
-*Warning: this step may take awhile (5+ minutes), because it builds shapely from source.*
-
-3. **Install Starplot:**
+2. **Install Starplot:**
 ```
 pip install starplot
 ```
@@ -35,19 +24,23 @@ pip install starplot
 apt-get install libgeos-dev libgdal-dev
 ```
 
-2. **Install Shapely:**
-```
-pip install --no-binary :all: shapely
-```
-*Warning: this step may take awhile (5+ minutes), because it builds shapely from source.*
-
-3. **Install Starplot:**
+2. **Install Starplot:**
 ```
 pip install starplot
 ```
 
----
-
 !!! note "What about Windows?"
 
     I haven't tried installing Starplot on Windows, but if you have and would like to share instructions, please feel free to [open a pull request on GitHub](https://github.com/steveberardi/starplot) with an update to this file (`docs/installation.md`). Thanks! :)
+
+---
+
+## Troubleshooting
+
+### Segmentation Fault with map plots
+
+If you're seeing "segmentation fault" errors when creating map plots, you may have to install [shapely](https://shapely.readthedocs.io/en/stable/index.html) from source for your runtime environment:
+```
+pip install --no-binary :all: shapely
+```
+*Warning: this may take awhile (5+ minutes), because it builds shapely from source.*

docs/images/example_2.png

@@ -190,11 +190,13 @@ Starplot has a bunch of built-in style extensions (all imported from `starplot.s
         show_root_heading: true
         show_docstring_attributes: true
 
+
 ::: starplot.styles.PolygonStyle
     options:
         show_root_heading: true
         show_docstring_attributes: true
 
+
 ::: starplot.styles.LabelStyle
     options:
         show_root_heading: true
@@ -213,6 +215,11 @@ Starplot has a bunch of built-in style extensions (all imported from `starplot.s
         show_root_heading: true
         show_docstring_attributes: true
 
+::: starplot.styles.LegendStyle
+    options:
+        show_root_heading: true
+        show_docstring_attributes: true
+
 
 ---
 ::: starplot.styles.FillStyleEnum
@@ -245,6 +252,12 @@ Starplot has a bunch of built-in style extensions (all imported from `starplot.s
         show_docstring_attributes: true
         members: true
 
+::: starplot.styles.LegendLocationEnum
+    options:
+        show_root_heading: true
+        show_docstring_attributes: true
+        members: true
+
 ---
 
 ## Style Extensions

docs/images/example_3.png

@@ -1,11 +1,9 @@
 
 <!-- Here are some planned features coming soon to Starplot: -->
 
-- ⭐ **Tycho stars**
-- 🌖 **Moon**
-- 📋 **Map legends**
-- ⚖️ **Better auto font-size adjustment**
-- ☄️ **Better label collision detection and handling**
-- 🔭 **Scope plots** - that will simulate what you'll see through a telescope eyepiece
+- ⭐ Custom markers
+- 🔭 Scope plots - that will simulate what you'll see through a telescope eyepiece
+- ⚖️ Better auto font-size adjustment
+- ☄️ Better label collision detection and handling
 
 ✨ Clear Skies! ✨

docs/installation.md

@@ -10,6 +10,11 @@
             "font_size": 7,
             "font_alpha": 0.9,
         },
+        "legend": {
+            "location": "lower right",  # show legend inside map
+            "num_columns": 1,
+            "background_alpha": 1,
+        },
     },
 )
 style.star.label.font_size = 11

docs/reference-styling.md

@@ -22,6 +22,7 @@ dependencies = [
     "numpy >= 1.22.1",
     "pandas >= 1.4.0",
     "pydantic >= 2.0.3",
+    "shapely >= 2.0.1",
     "skyfield >= 1.41",
     "adjustText >= 0.8",
     "cartopy >= 0.21.1",

docs/roadmap.md

@@ -2,6 +2,7 @@ matplotlib==3.7.2
 numpy==1.25.2
 pandas==2.0.3
 pydantic==2.0.3
+shapely==2.0.1
 skyfield==1.46
 adjustText==0.8
 cartopy==0.22.0