Step 3

.github/workflows/deploy.yml

@@ -0,0 +1,47 @@
+name: deploy-book
+
+# Only run this when the master branch changes
+on:
+  push:
+    branches:
+    - step1
+    # If your git repository has the Jupyter Book within some-subfolder next to
+    # unrelated files, you can make this run only if a file within that specific
+    # folder has been modified.
+    #
+    # paths:
+    # - some-subfolder/**
+
+# This job installs dependencies, builds the book, and pushes it to `gh-pages`
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+
+    # Install dependencies
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+
+    - name: Install dependencies
+      run: |
+        pip install -r requirements.txt
+
+    - name: Install randomly
+      run: |
+        pip install .
+
+
+    # Build the book
+    - name: Build the book
+      run: |
+        jupyter-book build docs/
+
+    # Push the book's HTML to github-pages
+    - name: GitHub Pages action
+      uses: peaceiris/[email protected]
+      with:
+        github_token: ${{ secrets.PERSONAL_TOKEN }}
+        publish_dir: docs/_build/html

docs/_config.yml

@@ -0,0 +1,94 @@
+#######################################################################################
+# A default configuration that will be loaded for all jupyter books
+# Users are expected to override these values in their own `_config.yml` file.
+# This is also the "master list" of all allowed keys and values.
+
+#######################################################################################
+# Book settings
+title                       : Jovan's Jupyter Book  # The title of the book. Will be placed in the left navbar.
+author                      : The Jupyter Book community  # The author of the book
+copyright                   : "2021"  # Copyright year to be placed in the footer
+logo                        : ""  # A path to the book logo
+# Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb")
+exclude_patterns            : [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints"]
+# Auto-exclude files not in the toc
+only_build_toc_files        : false
+
+#######################################################################################
+# Execution settings
+execute:
+  execute_notebooks         : auto  # Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off")
+  cache                     : ""    # A path to the jupyter cache that will be used to store execution artifacts. Defaults to `_build/.jupyter_cache/`
+  exclude_patterns          : []    # A list of patterns to *skip* in execution (e.g. a notebook that takes a really long time)
+  timeout                   : 30    # The maximum time (in seconds) each notebook cell is allowed to run.
+  run_in_temp               : false # If `True`, then a temporary directory will be created and used as the command working directory (cwd),
+                                    # otherwise the notebook's parent directory will be the cwd.
+  allow_errors              : false # If `False`, when a code cell raises an error the execution is stopped, otherwise all cells are always run.
+  stderr_output             : show  # One of 'show', 'remove', 'remove-warn', 'warn', 'error', 'severe'
+
+#######################################################################################
+# Parse and render settings
+parse:
+  myst_enable_extensions:  # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
+    # - amsmath
+    - colon_fence
+    # - deflist
+    - dollarmath
+    # - html_admonition
+    # - html_image
+    - linkify
+    # - replacements
+    # - smartquotes
+    - substitution
+    - tasklist
+  myst_url_schemes: [mailto, http, https] # URI schemes that will be recognised as external URLs in Markdown links
+  myst_dmath_double_inline: true  # Allow display math ($$) within an inline context
+
+#######################################################################################
+# HTML-specific settings
+html:
+  favicon                   : ""  # A path to a favicon image
+  use_edit_page_button      : true  # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in
+  use_repository_button     : true  # Whether to add a link to your repository button
+  use_issues_button         : true  # Whether to add an "open an issue" button
+  use_multitoc_numbering    : true   # Continuous numbering across parts/chapters
+  extra_navbar              : Powered by <a href="https://jupyterbook.org">Jupyter Book</a>  # Will be displayed underneath the left navbar.
+  extra_footer              : ""  # Will be displayed underneath the footer.
+  google_analytics_id       : ""  # A GA id that can be used to track book views.
+  home_page_in_navbar       : true  # Whether to include your home page in the left Navigation Bar
+  baseurl                   : ""  # The base URL where your book will be hosted. Used for creating image previews and social links. e.g.: https://mypage.com/mybook/
+  comments:
+    hypothesis              : false
+    utterances              : false
+
+#######################################################################################
+# LaTeX-specific settings
+latex:
+  latex_engine              : pdflatex  # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'
+  use_jupyterbook_latex     : true # use sphinx-jupyterbook-latex for pdf builds as default
+
+#######################################################################################
+# Launch button settings
+launch_buttons:
+  notebook_interface        : classic  # The interface interactive links will activate ["classic", "jupyterlab"]
+  binderhub_url             : https://mybinder.org  # The URL of the BinderHub (e.g., https://mybinder.org)
+  jupyterhub_url            : ""  # The URL of the JupyterHub (e.g., https://datahub.berkeley.edu)
+  thebe                     : false  # Add a thebe button to pages (requires the repository to run on Binder)
+  colab_url                 : "" # The URL of Google Colab (https://colab.research.google.com)
+
+repository:
+  url                       : https://github.com/executablebooks/jupyter-book  # The URL to your book's repository
+  path_to_book              : ""  # A path to your book's folder, relative to the repository root.
+  branch                    : master  # Which branch of the repository should be used when creating links
+
+#######################################################################################
+# Advanced and power-user settings
+sphinx:
+  extra_extensions          : [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode"
+  ]  # A list of extra extensions to load by Sphinx (added to those already used by JB).
+  local_extensions          :   # A list of local extensions to load by sphinx specified by "name: path" items
+  recursive_update          : false # A boolean indicating whether to overwrite the Sphinx config (true) or recursively update (false)
+  config                    :   # key-value pairs to directly over-ride the Sphinx configuration

docs/_toc.yml

@@ -0,0 +1,10 @@
+format: jb-book
+root: index
+parts:
+  - caption: Guides
+    chapters:
+    - file: guides/install
+    - file: guides/points
+  - caption: API reference
+    chapters:
+    - glob: api/*

docs/api/points.rst

@@ -0,0 +1,7 @@
+randomly.points
+===============
+
+.. automodule:: randomly.points
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/guides/install.md

@@ -0,0 +1,13 @@
+# Installation of the randomly package
+
+## Using pip
+```bash
+python3 -m pip install -e .
+```
+
+```{tip}
+The `.` at the end is the file path to the `randomly/` directory. If we 
+are already in that directory, we can use `.` 
+```
+
+## Using miniconda

docs/guides/points.ipynb

@@ -0,0 +1,77 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Guide to `points.py` module"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from randomly.points import generate_poisson_points"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "points = generate_poisson_points((0.5, 0.8, 1.5, 1.0), 10)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "numpy.ndarray"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "type(points)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Jovan was here"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/index.md

@@ -0,0 +1,6 @@
+# Welcome to randomly documentation
+
+```{tableofcontents}
+```
+
+Jovan was here

randomly/facts.py

@@ -1,8 +1,9 @@
+from typing import Literal
 import requests
 from requests.exceptions import RequestException
+from typing import Literal
 
-
-def generate_random_fact(output_format, language):
+def generate_random_fact(output_format, language: Literal["en", "de"]):
     if language not in {"en", "de"}:
         raise ValueError(f"{language} is not supported.")
 

randomly/palette.py

@@ -3,6 +3,17 @@
 
 
 def plot_palette(model):
+    """_summary_
+
+    Args:
+        model (_type_): _description_
+
+    Raises:
+        ValueError: _description_
+
+    Returns:
+        _type_: _description_
+    """
     if model not in {"default", "ui"}:
         raise ValueError(f"{model} is not supported.")
 

randomly/password.py

@@ -1,8 +1,10 @@
 import random
 import string
+from typing import Optional, Iterable
 
-
-def generate_password(chars, punctuation, invalid_chars=None):
+def generate_password(chars:int, punctuation:bool, 
+    invalid_chars:Optional[Iterable]=None
+) -> str:
     valid_chars = string.ascii_letters + string.digits
 
     if punctuation:

randomly/points.py

@@ -1,13 +1,28 @@
 import numpy as np
 from scipy.stats import poisson, uniform
+# from typing import Tuple # Tuple has been deprecated in pyton 3.9
 
+def generate_poisson_points(
+        bounds: tuple[float,float,float,float], 
+        rate: float
+    ) -> np.ndarray:
+    """Generates a numpy array of 2D points within 2D bounds
 
-def generate_poisson_points(bounds, rate):
+    Args:
+        bounds: (xmin, ymin, xmax, ymax)
+        rate: per-unit fill
+
+    Returns:
+        np.ndarray: 2D numpy array
+    """
+    # extract xy ranges from the bounds
     dx = bounds[2] - bounds[0]
     dy = bounds[3] - bounds[1]
 
-    N = poisson(rate * dx * dy).rvs()
-    xs = uniform.rvs(0, dx, ((N, 1))) + bounds[0]
+    # generate random values
+    N = poisson(rate * dx * dy).rvs() 
+    xs = uniform.rvs(0, dx, ((N, 1))) + bounds[0] 
     ys = uniform.rvs(0, dy, ((N, 1))) + bounds[1]
-
+
+    # packing the output into a numpy array
     return np.hstack((xs, ys))