Merge branch 'master' into django-flashcards-app

Author: martin-martin

document-your-python-project-with-mkdocs/README.md

@@ -0,0 +1,49 @@
+# Build Your Python Project Documentation With MkDocs
+
+This folder contains the source code and an example documentation built with [MkDocs](https://www.mkdocs.org), using the [Material for MkDocs](https://github.com/squidfunk/mkdocs-material) theme and the [mkdocstrings](https://mkdocstrings.github.io) plugin for docstring code discovery.
+
+The code used is intentionally kept basic and represents an unnecessary reproduction of fundamental math operations. This is done to keep the focus on _documenting_ a Python project, rather than the project's code.
+
+You should be able to follow the same process and use the same concepts for your own Python project with more interesting code.
+
+## Setup
+
+To view the documentation project, navigate to `source_code_final/` and install the dependencies into a new virtual environment:
+
+**Linux, macOS:**
+
+```bash
+$ cd source_code_final
+$ python3 -m venv venv
+$ source venv/bin/activate
+(venv) $ python -m pip install -r requirements.txt
+```
+
+**Windows:**
+
+```powershell
+PS> cd source_code_final
+PS> python -m venv venv
+PS> venv\bin\Activate.ps1
+(venv) PS> python -m pip install -r requirements.txt
+```
+
+Once you're set up and you've installed the dependencies, you can serve the project:
+
+```bash
+(venv) $ mkdocs serve
+```
+
+Navigate to your localhost at port `8000` to view the generated documentation.
+
+## Notes
+
+Part of the documentation is auto-generated from docstrings in `source_code_final/calculator/`. The mkdocstrings package renders docstrings from module and package-level docstrings, as well as function docstrings in `calculations.py`.
+
+You can find the relevant notation in `docs/index.md` and `docs/reference.md`.
+
+The rest of the documentation is written in Markdown and split up across several files in the `docs/` directory.
+
+In this project you can see that you can create project documentation that is partly auto-generated from your docstrings, interweaved with explanatory text and best-practice project documentation structure.
+
+There is also an associated tutorial where you can learn how to [Build Your Python Project Documentation With MkDocs](https://realpython.com/python-project-documentation-with-mkdocs) step-by-step.

document-your-python-project-with-mkdocs/source_code_final/calculator/__init__.py

@@ -0,0 +1,6 @@
+"""Do math with your own functions.
+
+Modules exported by this package:
+
+- `calculations`: Provide several sample math calculations.
+"""

document-your-python-project-with-mkdocs/source_code_final/calculator/calculations.py

@@ -0,0 +1,112 @@
+"""Provide several sample math calculations.
+
+This module allows the user to make mathematical calculations.
+
+Examples:
+    >>> from calculator import calculations
+    >>> calculations.add(2, 4)
+    6.0
+    >>> calculations.multiply(2.0, 4.0)
+    8.0
+    >>> from calculator.calculations import divide
+    >>> divide(4.0, 2)
+    2.0
+
+The module contains the following functions:
+
+- `add(a, b)` - Returns the sum of two numbers.
+- `subtract(a, b)` - Returns the difference of two numbers.
+- `multiply(a, b)` - Returns the product of two numbers.
+- `divide(a, b)` - Returns the quotient of two numbers.
+"""
+
+from typing import Union
+
+
+def add(a: Union[float, int], b: Union[float, int]) -> float:
+    """Compute and return the sum of two numbers.
+
+    Examples:
+        >>> add(4.0, 2.0)
+        6.0
+        >>> add(4, 2)
+        6.0
+
+    Args:
+        a: A number representing the first addend in the addition.
+        b: A number representing the second addend in the addition.
+
+    Returns:
+        A number representing the artihmetic sum of `a` and `b`.
+    """
+
+    return float(a + b)
+
+
+def subtract(a: Union[float, int], b: Union[float, int]) -> float:
+    """Calculate the difference of two numbers.
+
+    Examples:
+        >>> subtract(4.0, 2.0)
+        2.0
+        >>> subtract(4, 2)
+        2.0
+
+    Args:
+        a: A number representing the minuend in the subtraction.
+        b: A number representing the subtrahend in the subtraction.
+
+    Returns:
+        A number representing the difference between `a` and `b`.
+    """
+
+    return float(a - b)
+
+
+def multiply(a: Union[float, int], b: Union[float, int]) -> float:
+    """Compute and return the product of two numbers.
+
+    Examples:
+        >>> multiply(4.0, 2.0)
+        8.0
+        >>> multiply(4, 2)
+        8.0
+
+    Args:
+        a: A number representing the multiplicand in the multiplication.
+        b: A number representing the multiplier in the multiplication.
+
+    Returns:
+        A number representing the product of `a` and `b`.
+    """
+
+    return float(a * b)
+
+
+def divide(a: Union[float, int], b: Union[float, int]) -> float:
+    """Compute and return the quotient of two numbers.
+
+    Examples:
+        >>> divide(4.0, 2.0)
+        2.0
+        >>> divide(4, 2)
+        2.0
+        >>> divide(4, 0)
+        Traceback (most recent call last):
+        ...
+        ZeroDivisionError: division by zero
+
+    Args:
+        a: A number representing the dividend in the division.
+        b: A number representing the divisor in the division.
+
+    Returns:
+        A number representing the quotient of `a` and `b`.
+
+    Raises:
+        ZeroDivisionError: An error occurs when the divisor is `0`.
+    """
+
+    if b == 0:
+        raise ZeroDivisionError("division by zero")
+    return float(a / b)

document-your-python-project-with-mkdocs/source_code_final/docs/explanation.md

@@ -0,0 +1,17 @@
+# Explanation
+
+This part of the project documentation focuses on an
+**understanding-oriented** approach. You'll get a
+chance to read about the background of the project,
+as well as reasoning about how it was implemented.
+
+> **Note:** Expand this section by considering the
+> following points:
+
+- Give context and background on your library
+- Explain why you created it
+- Provide multiple examples and approaches of how
+    to work with it
+- Help the reader make connections
+- Avoid writing instructions or technical descriptions
+    here

document-your-python-project-with-mkdocs/source_code_final/docs/how-to-guides.md

@@ -0,0 +1,42 @@
+# How-To Guides
+
+This part of the project documentation focuses on a
+**problem-oriented** approach. You'll tackle common
+tasks that you might have, with the help of the code
+provided in this project.
+
+## How To Add Two Numbers?
+
+You have two numbers and you need to add them together.
+You're in luck! The `calculator` package can help you
+get this done.
+
+Download the code from this GitHub repository and place
+the `calculator/` folder in the same directory as your
+Python script:
+
+    your_project/
+    │
+    ├── calculator/
+    │   ├── __init__.py
+    │   └── calculations.py
+    │
+    └── your_script.py
+
+Inside of `your_script.py` you can now import the
+`add()` function from the `calculator.calculations`
+module:
+
+    # your_script.py
+    from calculator.calculations import add
+
+After you've imported the function, you can use it
+to add any two numbers that you need to add:
+
+    # your_script.py
+    from calculator.calculations import add
+
+    print(add(20, 22))  # OUTPUT: 42.0
+
+You're now able to add any two numbers, and you'll
+always get a `float` as a result.

document-your-python-project-with-mkdocs/source_code_final/docs/index.md

@@ -0,0 +1,36 @@
+# Calculator Docs
+
+This site contains the project documentation for the
+`calculator` project that is a toy module used in the
+Real Python tutorial
+[Build Your Python Project Documentation With MkDocs](
+    https://realpython.com/python-project-documentation-with-mkdocs/).
+Its aim is to give you a framework to build your
+project documentation using Python, MkDocs,
+mkdocstrings, and the Material for MkDocs theme.
+
+## Table Of Contents
+
+The documentation follows the best practice for
+project documentation as described by Daniele Procida
+in the [Diátaxis documentation framework](https://diataxis.fr/)
+and consists of four separate parts:
+
+1. [Tutorials](tutorials.md)
+2. [How-To Guides](how-to-guides.md)
+3. [Reference](reference.md)
+4. [Explanation](explanation.md)
+
+Quickly find what you're looking for depending on
+your use case by looking at the different pages.
+
+## Project Overview
+
+::: calculator.__init__
+
+## Acknowledgements
+
+I want to thank my house plants for providing me with
+a negligible amount of oxygen each day. Also, I want
+to thank the sun for providing more than half of their
+nourishment free of charge.

document-your-python-project-with-mkdocs/source_code_final/docs/reference.md

@@ -0,0 +1,8 @@
+# Reference
+
+This part of the project documentation focuses on
+an **information-oriented** approach. Use it as a
+reference for the technical implementation of the
+`calculator` project code.
+
+::: calculator.calculations

document-your-python-project-with-mkdocs/source_code_final/docs/tutorials.md

@@ -0,0 +1,18 @@
+# Tutorials
+
+This part of the project documentation focuses on a
+**learning-oriented** approach. You'll learn how to
+get started with the code in this project.
+
+> **Note:** Expand this section by considering the
+> following points:
+
+- Help newcomers with getting started
+- Teach readers about your library by making them
+    write code
+- Inspire confidence through examples that work for
+    everyone, repeatably
+- Give readers an immediate sense of achievement
+- Show concrete examples, no abstractions
+- Provide the minimum necessary explanation
+- Avoid any distractions

document-your-python-project-with-mkdocs/source_code_final/mkdocs.yml

@@ -0,0 +1,15 @@
+site_name: Calculation Docs
+
+theme:
+  name: "material"
+
+plugins:
+  - mkdocstrings
+
+nav:
+  - Calculation Docs: index.md
+  - tutorials.md
+  - How-To Guides: how-to-guides.md
+  - reference.md
+  - explanation.md
+  

document-your-python-project-with-mkdocs/source_code_final/requirements.txt

@@ -0,0 +1,24 @@
+click==8.1.3
+ghp-import==2.1.0
+importlib-metadata==4.11.3
+Jinja2==3.1.2
+Markdown==3.3.6
+MarkupSafe==2.1.1
+mergedeep==1.3.4
+mkdocs==1.3.0
+mkdocs-autorefs==0.4.1
+mkdocs-material==8.2.13
+mkdocs-material-extensions==1.0.3
+mkdocstrings==0.18.1
+mkdocstrings-python-legacy==0.2.2
+packaging==21.3
+Pygments==2.12.0
+pymdown-extensions==9.4
+pyparsing==3.0.8
+python-dateutil==2.8.2
+pytkdocs==0.16.1
+PyYAML==6.0
+pyyaml_env_tag==0.1
+six==1.16.0
+watchdog==2.1.7
+zipp==3.8.0