Update

UN-GCPDS · Feb 25, 2024 · ff34225 · ff34225
1 parent a3a73b8
commit ff34225
Show file tree

Hide file tree

Showing 9 changed files with 890 additions and 11 deletions.
diff --git a/docs/source/_static/dunderlab_custom.css b/docs/source/_static/dunderlab_custom.css
@@ -1,3 +1,8 @@
+:root {
+  --accent: #FC4DB5;
+  --accent_dark: #b0357e;
+}
+
 pre.literal-block,
 .highlight pre {
     background-color: #fbfbfb;

diff --git a/docs/source/notebooks/01_set_up/01-github.ipynb b/docs/source/notebooks/01_set_up/01-github.ipynb
@@ -15,7 +15,7 @@
    "id": "e7d0761f-a1ce-4403-aecf-3e6988dd1a0b",
    "metadata": {},
    "source": [
-    "1. **Repository Naming Convention**: \n",
+    "1. **Repository Naming Convention**:\n",
     "   - **Format**: The repository name must follow the `python-gcpds.<module_name>` pattern.\n",
     "   - **Case Sensitivity**: Always use lowercase for `<module_name>`. This ensures uniformity and avoids confusion caused by case-sensitive URLs.\n",
     "   - **Descriptiveness**: The module name should be highly descriptive. It should clearly reflect the module's purpose or functionality. Avoid using abbreviations unless they are widely understood in the domain.\n",

diff --git a/docs/source/notebooks/03_python_module/01-structure.ipynb b/docs/source/notebooks/03_python_module/01-structure.ipynb
@@ -5,7 +5,95 @@
    "id": "07383f1c-a38c-4045-8386-9132455908a7",
    "metadata": {},
    "source": [
-    "# Module Directory Structure"
+    "# Module Directory Structure\n",
+    "\n",
+    "In this tutorial, we will cover the process of transitioning your code from Jupyter notebooks to a structured Python module. The focus will be on creating a module named \"gcpds\" with a chosen submodule.\n",
+    "\n",
+    "## Structuring Your Module\n",
+    "\n",
+    "Your module structure should follow this pattern:\n",
+    "\n",
+    "\n",
+    "```plaintext\n",
+    "gcpds/\n",
+    "└── submodule/\n",
+    "├── init.py\n",
+    "├── optional_file_1.py\n",
+    "└── optional_file_2.py\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e41d2fa3-04e2-46ef-b3a1-564dd693ab43",
+   "metadata": {},
+   "source": [
+    "## Using `__init__.py`\n",
+    "\n",
+    "The `__init__.py` file is suitable for simpler submodules.\n",
+    "\n",
+    "**Example: Simple Class in `__init__.py`**\n",
+    "\n",
+    "Suppose you have a basic class `SimpleClass` in your Jupyter notebook. Here's how to include it in `__init__.py`:\n",
+    "\n",
+    "```python\n",
+    "# gcpds/submodule/__init__.py\n",
+    "\n",
+    "class SimpleClass:\n",
+    "    def __init__(self):\n",
+    "        self.message = \"Hello from SimpleClass\"\n",
+    "\n",
+    "    def greet(self):\n",
+    "        return self.message\n",
+    "```\n",
+    "\n",
+    "**Importing from `__init__.py`**\n",
+    "\n",
+    "To use `SimpleClass` in your script:\n",
+    "\n",
+    "```python\n",
+    "from gcpds.submodule import SimpleClass\n",
+    "\n",
+    "simple_obj = SimpleClass()\n",
+    "print(simple_obj.greet())  # Outputs: Hello from SimpleClass\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c89dc204-4a8d-4c39-9c1a-48b3d145b3fc",
+   "metadata": {},
+   "source": [
+    "## Using `optional_file_1.py`\n",
+    "\n",
+    "For more complex functionalities, additional files like `optional_file_1.py` are used.\n",
+    "\n",
+    "**Example: Class in `optional_file_1.py`**\n",
+    "\n",
+    "Imagine you have a more complex class, `ComplexClass`, in your Jupyter notebook. Here's how to include it in `optional_file_1.py`:\n",
+    "\n",
+    "```python\n",
+    "# gcpds/submodule/optional_file_1.py\n",
+    "\n",
+    "class ComplexClass:\n",
+    "    def __init__(self, param):\n",
+    "        self.param = param\n",
+    "\n",
+    "    def complex_method(self):\n",
+    "        # Complex implementation\n",
+    "        return f\"Complex output with {self.param}\"\n",
+    "```\n",
+    "\n",
+    "**Importing from `optional_file_1.py`**\n",
+    "\n",
+    "To use `ComplexClass` in your script:\n",
+    "\n",
+    "```python\n",
+    "from gcpds.submodule.optional_file_1 import ComplexClass\n",
+    "\n",
+    "complex_obj = ComplexClass(\"parameter\")\n",
+    "print(complex_obj.complex_method())  # Outputs: Complex output with parameter\n",
+    "```"
    ]
   }
  ],

diff --git a/docs/source/notebooks/03_python_module/02-from_notebooks.ipynb b/docs/source/notebooks/03_python_module/02-from_notebooks.ipynb
@@ -0,0 +1,97 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "93f4ef0d-1cce-43fc-baa5-85ea4e6592ec",
+   "metadata": {},
+   "source": [
+    "# Transitioning from Jupyter Notebooks to Jupyter Notebooks\n",
+    "\n",
+    "Moving code from Jupyter notebooks to a Python module is a structured process that involves organizing your code efficiently. This transition is crucial for enhancing readability, maintainability, and collaboration.\n",
+    "\n",
+    "1. **Isolate Logic**: \n",
+    "   - **Identify Core Components**: Go through your Jupyter notebook and pinpoint the core logic, functions, and classes. These are the elements you'll want to transfer to your Python module.\n",
+    "   - **Separate Concerns**: Ensure each function or class has a single responsibility. This approach simplifies maintenance and improves code clarity.\n",
+    "      \n",
+    "2. **Code Cleanup**:\n",
+    "    - **Follow PEP 8 Standards**: Adhere to [PEP 8](https://www.python.org/dev/peps/pep-0008/) guidelines to ensure code consistency and readability. This includes proper naming conventions, indentation, and spacing.\n",
+    "    - **Refactor and Comment**: Simplify complex code blocks and add comments where necessary. Comments should explain the why, not just the how, providing context for your code.\n",
+    "    - **Remove Redundancies**: Eliminate any redundant or unnecessary code that does not contribute to the core functionality.\n",
+    "\n",
+    "3. **File Creation**:\n",
+    "    - **Setup Module Directory**: Create the `gcpds` directory and the chosen submodule directory within it.\n",
+    "    - **Create Python Files**: Based on the complexity, create either a single `__init__.py` file for simple submodules or multiple files like `optional_file_1.py` for more complex ones.\n",
+    "\n",
+    "4. **Code Transfer**:\n",
+    "    - **Extract Code from Notebook**: Convert the code cells from your Jupyter notebook into Python script format.\n",
+    "    - **Organize by Functionality**: Group related functions or classes together. If they are part of a common theme or functionality, they should reside in the same file.\n",
+    "    - **Adjust for Script Format**: Transform interactive Jupyter code (like inline plots or progress bars) into a format suitable for scripts.\n",
+    "\n",
+    "5. **Testing**:\n",
+    "    - **Unit Tests**: Write unit tests for each function and class to ensure they behave as expected. This is crucial for identifying bugs early.\n",
+    "    - **Test as Standalone Components**: Ensure that each part of your code can function independently. This improves modularity and reusability.\n",
+    "    - **Iterative Testing**: Test your module iteratively as you transfer code. This helps in identifying issues early in the transition process.\n",
+    "\n",
+    "6. **Documentation**:\n",
+    "    - **Docstrings**: Include docstrings for each function and class to explain their purpose, parameters, and return values.\n",
+    "    - **Module Documentation**: Provide a README file or equivalent documentation within the module, detailing its purpose, contents, and usage instructions.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "502b4aa9-f29e-4dfc-bc9b-a9782f2dc561",
+   "metadata": {},
+   "source": [
+    "# Using Jupyter Notebooks for Testing and Exploration\n",
+    "\n",
+    "In the development workflow, Jupyter Notebooks play a crucial role in the initial stages of testing and exploration. However, for creating a robust, maintainable, and reusable codebase, it's essential to transition the main code to a Python package. This section outlines the reasons and the best practices for this approach.\n",
+    "\n",
+    "## The Role of Jupyter Notebooks\n",
+    "\n",
+    "1. **Exploratory Analysis**:\n",
+    "   - **Interactive Environment**: Jupyter Notebooks offer an interactive environment, making them ideal for exploratory data analysis, quick tests, and prototyping.\n",
+    "   - **Visualization**: They are excellent for visualizations and seeing immediate outputs, which aids in understanding data and debugging.\n",
+    "\n",
+    "2. **Limitations for Production**:\n",
+    "   - **Not Ideal for Large Codebases**: Notebooks can become cumbersome for managing larger codebases.\n",
+    "   - **Version Control Challenges**: Notebooks often pose challenges with version control systems, making collaboration and code tracking more difficult.\n",
+    "\n",
+    "                                                         \n",
+    "## Transition to Python Packages\n",
+    "\n",
+    "1. **Structured Codebase**:\n",
+    "   - **Maintainability**: A Python package structure allows for better organization of code into modules and submodules, enhancing readability and maintainability.\n",
+    "   - **Scalability**: It's easier to scale and extend functionalities in a package format compared to a notebook.\n",
+    "\n",
+    "2. **Installation and Reusability**:\n",
+    "   - **Easy Distribution**: Packages can be easily distributed and installed using tools like `pip`. This makes sharing your code with others more straightforward.\n",
+    "   - **Reuse Across Projects**: Once packaged, your code can be imported and reused across different projects, saving time and effort.\n",
+    "\n",
+    "3. **Testing and Deployment**:\n",
+    "   - **Unit Testing**: Packages allow for comprehensive unit testing of functions and classes, ensuring code reliability.\n",
+    "   - **Deployment Ready**: Code in a package is more deployment-ready for production environments.                                                         "
+   ]
+  }
+ ],
+ "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.11.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}