diff --git a/.github/workflows/automated-setup.yml b/.github/workflows/automated-setup.yml new file mode 100644 index 0000000..cbd032c --- /dev/null +++ b/.github/workflows/automated-setup.yml @@ -0,0 +1,65 @@ +# .github/workflows + +name: Automated Setup Generation + +# Workflow triggers +on: + workflow_dispatch: # Allows manual triggering of the workflow + push: # Triggers the workflow on every push to the repository + +jobs: + format-code-customized: + runs-on: ubuntu-latest # Specifies the virtual machine to use, in this case, the latest version of Ubuntu + + # Defines permissions for this job + permissions: + contents: write # Permissions to write to the repository + + steps: + - uses: actions/checkout@v4 # Checks out the code from the repository + + # Step to update and prepare the documentation + - name: Prepare and Update Documentation + + run: | + # Verifica si setup.py existe, si no, lo crea + if [ ! -f "setup.py" ]; then + echo """import os + from setuptools import setup + + with open(os.path.join(os.path.dirname(__file__), 'README.md')) as readme: + README = readme.read() + + os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir))) + + setup( + name=\"${{ vars.MODULE }}\", + version='0.1', + packages=[\"${{ vars.MODULE }}\"], + author=\"${{ vars.AUTHOR }}\", + author_email=\"${{ vars.EMAIL }}\", + maintainer=\"${{ vars.AUTHOR }}\", + maintainer_email=\"${{ vars.EMAIL }}\", + download_url='', + install_requires=[ + ], + scripts=[ + ], + include_package_data=True, + license='Simplified BSD License', + description=\"\", + zip_safe=False, + long_description=README, + long_description_content_type='text/markdown', + python_requires='>=3.7', + + #https://pypi.org/classifiers/ + classifiers=[ + ], + ) + """ >> setup.py + fi + + + # Commit all changed files back to the repository + - uses: stefanzweifel/git-auto-commit-action@v5 diff --git a/.github/workflows/automated-sphinx-docs.yml b/.github/workflows/automated-sphinx-docs.yml new file mode 100644 index 0000000..40194ff --- /dev/null +++ b/.github/workflows/automated-sphinx-docs.yml @@ -0,0 +1,82 @@ +# .github/workflows + +name: Automated Documentation and Code Formatting + +# Workflow triggers +on: + workflow_dispatch: # Allows manual triggering of the workflow + push: # Triggers the workflow on every push to the repository + +jobs: + format-code-customized: + runs-on: ubuntu-latest # Specifies the virtual machine to use, in this case, the latest version of Ubuntu + + # Defines permissions for this job + permissions: + contents: write # Permissions to write to the repository + + steps: + - uses: actions/checkout@v4 # Checks out the code from the repository + + # Step to update and prepare the documentation + - name: Prepare and Update Documentation + + run: | + # Pulls necessary Docker images for documentation + docker pull dunderlab/docs + docker pull sphinxdoc/sphinx-latexpdf + + # Installs required Python packages + pip install nbsphinx + pip install dunderlab-docs + + # Sets up initial documentation if a 'docs' directory does not exist + if [ ! -d "docs" ]; then + dunderlab_docs quickstart '--project "${{ vars.PROJECT_NAME }}" --author "${{ vars.AUTHOR }}" --extensions nbsphinx,dunderlab.docs --no-batchfile --quiet --sep' + fi + + # Generates API documentation and builds HTML and Latex PDF if SUBMODULE is set + if [ -n "${{ vars.SUBMODULE }}" ]; then + dunderlab_docs apidoc "${{ vars.MODULE }}" + dunderlab_docs build html "${{ vars.MODULE }}/${{ vars.SUBMODULE }}" + dunderlab_docs build latexpdf "${{ vars.MODULE }}/${{ vars.SUBMODULE }}" + else + dunderlab_docs apidoc "${{ vars.MODULE }}" + dunderlab_docs build html "${{ vars.MODULE }}" + dunderlab_docs build latexpdf "${{ vars.MODULE }}" + fi + + # Adds a configuration file for Read the Docs + # Verifies if .readthedocs.yml exists, if not, creates it + if [ ! -f ".readthedocs.yml" ]; then + echo """# .readthedocs.yml + # Read the Docs configuration file + # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + + # Required + version: 2 + + # Build documentation in the docs/ directory with Sphinx + sphinx: + configuration: docs/source/conf.py + + # Optionally set the version of Python and requirements required to build your docs + python: + install: + - requirements: docs/requirements + + # Set the version of Python and other tools you might need + build: + os: ubuntu-22.04 + tools: + python: \"3.11\" + + formats: + - epub + - pdf + """ >> .readthedocs.yml + fi + + + # Commit all changed files back to the repository + - uses: stefanzweifel/git-auto-commit-action@v5 diff --git a/.gitignore b/.gitignore index 68bc17f..4d3e52a 100644 --- a/.gitignore +++ b/.gitignore @@ -158,3 +158,6 @@ cython_debug/ # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. #.idea/ + +*.wpr +*.wpu diff --git a/README.md b/README.md new file mode 100644 index 0000000..8249da1 --- /dev/null +++ b/README.md @@ -0,0 +1,56 @@ +# GCPDS - Documentation Guide + +Welcome to the "GCPDS - Documentation Guide". This guide serves as a comprehensive resource for setting up, configuring, and maintaining the documentation of projects under the General Computational Perception and Decision Systems (GCPDS) initiative. Our goal is to standardize the process of documentation across various modules and projects to enhance clarity, accessibility, and ease of use. + +The guide outlines a series of steps and best practices aimed at ensuring a seamless integration of Python modules with version control and automated documentation systems. By following these guidelines, developers and contributors will be able to maintain a high standard of code management and documentation, which is vital for collaborative development and the long-term success of the project. + +We cover everything from the initial setup of a GitHub repository, including naming conventions and configuration, to the integration with Read the Docs for automated documentation generation. Additionally, we discuss security practices, such as handling sensitive data through repository secrets and access tokens, to ensure the integrity and confidentiality of the project. + +Each section of this guide is designed to walk you through the necessary steps to achieve an efficient and secure workflow. By adhering to these guidelines, the GCPDS community can contribute to a robust and sustainable ecosystem for research and development in computational perception and decision systems. + +## Installation Instructions + +To integrate the `gcpds.docs` module into your Python environment, the process is straightforward and managed via `pip`, Python's package installer. Ensure that you have `pip` installed and that it is up to date to avoid any compatibility issues. Follow the command below to install the latest version of `gcpds.docs`: + + +```python +pip install -U gcpds.docs +``` + +This command will download and install the `gcpds.docs` module along with its dependencies. The `-U` flag ensures that if the package is already installed, it will be upgraded to the latest version. + +After the installation is complete, you can import and use `gcpds.docs` in your Python projects to enhance your documentation process. + +**Note:** It is recommended to perform this installation within a virtual environment to maintain a clean workspace and avoid version conflicts with other projects. + +## Introduction to Setting Up and Integrating a Python Module Repository + +This documentation provides a structured approach to setting up a Python module repository on GitHub and integrating it with external documentation and automation services. The objective is to streamline the process of repository management, code security, and documentation generation for Python projects. By following these guidelines, developers can ensure their projects are well-organized, secure, and easily maintainable. + +### Objectives + +1. **Establish Conventions**: Define a clear and descriptive naming convention for Python module repositories to maintain consistency and clarity across projects. + +2. **Secure Configuration**: Implement repository variables and secrets to manage environment configurations and sensitive information securely. + +3. **Access Management**: Generate a Personal Access Token (Classic) to provide secure access to GitHub resources, enabling automated processes and integrations. + +4. **Documentation Automation**: Create and configure a project on Read the Docs to facilitate automatic generation and hosting of project documentation. + +5. **Continuous Integration**: Set up webhooks between GitHub and Read the Docs to enable real-time documentation updates with each code commit, ensuring the latest project changes are always documented. + +By adhering to these steps, we aim to create a robust workflow that encapsulates best practices for repository setup, security, and documentation, while also leveraging automation to reduce manual effort and potential errors. + +### Steps Overview + +- **Guidelines for Python Module Repository Naming and Configuration on GitHub**: This section will guide you through the best practices for naming your Python module repository, setting it to public, and choosing the appropriate license. + +- **Configuring Repository Variables and Secrets on GitHub**: Here, you will learn how to securely store and manage environment-specific configurations within your GitHub repository settings. + +- **Creating a Personal Access Token (Classic) on GitHub**: This part of the documentation explains the process of creating a Personal Access Token to interact with GitHub's API securely. + +- **Creating a Project on Read the Docs**: We will go through the steps of setting up your project on Read the Docs, ensuring your documentation is automatically generated from your repository. + +- **Integrating GitHub with Webhooks for Read the Docs**: Lastly, you will set up a webhook to connect your GitHub repository with Read the Docs, allowing for automated documentation builds upon every commit. + +Following these guidelines will set a solid foundation for your Python projects on GitHub and ensure that your documentation is always up-to-date with your latest code changes. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/requirements b/docs/requirements new file mode 100644 index 0000000..3fdfbed --- /dev/null +++ b/docs/requirements @@ -0,0 +1,8 @@ +sphinx==7.0.0 +urllib3<2.0 +ipython +ipykernel +nbsphinx +sphinxcontrib-bibtex +pygments +dunderlab-docs diff --git a/docs/source/_modules/docs.rst b/docs/source/_modules/docs.rst new file mode 100644 index 0000000..3c843b3 --- /dev/null +++ b/docs/source/_modules/docs.rst @@ -0,0 +1,7 @@ +docs package +============ + +.. automodule:: docs + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..e846243 --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,11 @@ +img[alt*="border-image"] { + box-shadow: 0 3px 6px rgba(0,0,0,0.16), 0 3px 6px rgba(0,0,0,0.23); + width: 80%; + margin: 30px 10%; +} + + +div.sphinxsidebar ul li { + margin: 10px 0; + list-style: circle; +} diff --git a/docs/source/_static/dunderlab_custom.css b/docs/source/_static/dunderlab_custom.css new file mode 100644 index 0000000..715c1f8 --- /dev/null +++ b/docs/source/_static/dunderlab_custom.css @@ -0,0 +1,116 @@ +:root { + --accent: #FC4DB5; + --accent_dark: #b0357e; +} + +pre.literal-block, +.highlight pre { + background-color: #fbfbfb; + border: none !important; + border-radius: 2px; + font-size: 75%; +} + +.docutils.literal { + color: #FC4DB5; + padding: 1px 4px; + margin: 0 -2px; + border-radius: 2px; +} + +div.nbinput.container div.input_area { + border: none !important; +} + +a.reference { + border-bottom: 1px dotted #FC4DB5; + color: #FC4DB5; +} + +a.reference:hover { + border-bottom: 1px solid #b0357e; + color: #b0357e; +} + + + +h1 { + margin: 30px 0px 10px 0px !important; +} + + +.body { + max-width: unset !important; +} + + +img.logo { + + width: 210px; + +} + + +div.note { + background-color: #00ACC117; + border: 1px solid #00ACC15C; +} + + + +dl:not(.docutils) dt { + margin: 6px 0; + margin-top: 6px; + font-size: 90%; + line-height: normal; + background: #00ACC117; + color: #555; + border-top: solid 3px #00ACC15C; + padding: 6px; + font-family: mono; +} + +dl:not(.docutils) tt, +dl:not(.docutils) tt, +dl:not(.docutils) code { + font-weight: bold; +} + +dl:not(.docutils) tt.descname, +dl:not(.docutils) tt.descname, +dl:not(.docutils) code.descname { + font-weight: bold; +} + +dl:not(.docutils) dl dt { + margin-bottom: 6px; + border: none; + border-left: solid 3px #ccc; + background: #f0f0f0; + color: #555; +} + +.body > .highlight-ipython3 { + display: none; +} + +.toctree-wrapper .caption-text { + font-size: 30.6px; + font-family: Noto Sans; + font-weight: normal; + margin: 30px 0px 10px 0px; + padding: 0; +} + +.sphinxsidebarwrapper p.caption{ + font-size: 20px; +} + +.dunderlab-footer { + margin-top: 80px; + background-color: #7878780d; + padding: 15px 30px; + border: 1px solid #FC4DB5; + border-width: 3px 0 0 0; + border-radius: 5px; +} diff --git a/docs/source/_static/favicon.ico b/docs/source/_static/favicon.ico new file mode 100644 index 0000000..e11832f Binary files /dev/null and b/docs/source/_static/favicon.ico differ diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png new file mode 100644 index 0000000..8076d9a Binary files /dev/null and b/docs/source/_static/logo.png differ diff --git a/docs/source/_static/logo.svg b/docs/source/_static/logo.svg new file mode 100644 index 0000000..6251c45 --- /dev/null +++ b/docs/source/_static/logo.svg @@ -0,0 +1,78 @@ + + + + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..328415c --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,42 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'GCPDS - Docs' +copyright = '2024, Yeison Cardona' +author = 'Yeison Cardona' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'nbsphinx', + 'dunderlab.docs', +] + +templates_path = ['_templates'] +exclude_patterns = [] + +html_logo = '_static/logo.svg' +html_favicon = '_static/favicon.ico' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] + +html_theme_options = { + 'caption_font_family': 'Noto Sans', + 'font_family': 'Noto Sans', + 'head_font_family': 'Noto Sans', + 'page_width': '1280px', + 'sidebar_width': '300px', +} + +dunderlab_color_links = '#FC4DB5' +dunderlab_code_reference = True diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..b8c8927 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,34 @@ + +.. include:: notebooks/readme.rst + + +Documentation Overview +====================== + + +.. toctree:: + :maxdepth: 2 + :name: mastertoc + + notebooks/01-github + notebooks/02-github_secrets + notebooks/03-github_pat + notebooks/04-readthedocs + notebooks/05-github_and_readthedocs + notebooks/06-repository_structure_setup + + + + +.. only:: html + + Code Reference + ============== + + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` + + + + \ No newline at end of file diff --git a/docs/source/notebooks/01-github.ipynb b/docs/source/notebooks/01-github.ipynb new file mode 100644 index 0000000..9f1fd95 --- /dev/null +++ b/docs/source/notebooks/01-github.ipynb @@ -0,0 +1,122 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "11870f44-d8e9-4b81-bd2c-885e3927c82d", + "metadata": {}, + "source": [ + "# Guidelines for Python Module Repository Naming and Configuration on GitHub\n", + "\n", + "When setting up a new Python module repository on GitHub, it is essential to follow a set of standard practices to ensure the repository is organized, well-documented, and accessible to users and contributors. These guidelines provide a framework for naming conventions, visibility settings, and initial configuration steps that will lead to a clean, professional, and easy-to-use repository. Adhering to these practices not only facilitates collaboration and code management but also aligns with the best practices for open-source development." + ] + }, + { + "cell_type": "markdown", + "id": "e7d0761f-a1ce-4403-aecf-3e6988dd1a0b", + "metadata": {}, + "source": [ + "1. **Repository Naming Convention**: \n", + " - **Format**: The repository name must follow the `python-gcpds.` pattern.\n", + " - **Case Sensitivity**: Always use lowercase for ``. 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", + " \n", + "![border-image](_images/github_create_01.jpeg)" + ] + }, + { + "cell_type": "markdown", + "id": "9e611cff-bfe8-4d09-9469-d101babc2145", + "metadata": {}, + "source": [ + "2. **Repository Visibility**: \n", + " - **Public Access**: The repository must be set as public. This promotes transparency, fosters collaboration, and encourages community engagement.\n", + " - **Benefits of Public Repositories**: Public repositories can be freely accessed, forked, and contributed to by anyone. They facilitate open-source collaboration and knowledge sharing.\n", + "\n", + "![border-image](_images/github_create_02.jpeg)" + ] + }, + { + "cell_type": "markdown", + "id": "2394fbcc-eafb-469b-955c-9f02f7f575fc", + "metadata": {}, + "source": [ + "3. **README File**: \n", + " - **No Initial Requirement**: A README file is not initially required in the repository. This is because it will be generated automatically later on.\n", + " - **Automated Generation**: The README will be created automatically to ensure consistency and adherence to project standards. This process will include essential information such as module description, installation instructions, usage examples, and contact information for contributors.\n", + "\n", + "![border-image](_images/github_create_03.jpeg)" + ] + }, + { + "cell_type": "markdown", + "id": "508d73a7-635f-4e74-9873-03911b884e19", + "metadata": {}, + "source": [ + "4. **.gitignore Configuration**: \n", + " - **Python-Specific Setup**: The `.gitignore` file should be tailored for Python projects.\n", + " - **Exclusions**: It should exclude common Python temporary files and directories like `__pycache__`, `.pyc` files, virtual environment directories (`venv/`, `env/`), and other non-essential files.\n", + " - **Best Practices**: This practice keeps the repository clean and prevents unnecessary files from being tracked and shared.\n", + " \n", + "![border-image](_images/github_create_04.jpeg)" + ] + }, + { + "cell_type": "markdown", + "id": "fc67df51-2018-4ac3-8576-083d917a2c1e", + "metadata": {}, + "source": [ + "5. **License**: \n", + " - **BSD 2-Clause \"Simplified\" License**: Choose the BSD 2-Clause License for its simplicity and permissiveness.\n", + " - **License Features**: This license allows almost unrestricted freedom in using, modifying, and distributing your software, provided that copyright notices and disclaimers are preserved. It's ideal for open-source projects that aim for broad distribution and utilization.\n", + " - **Implications for Users**: Users and developers can integrate and use your software in almost any project, including proprietary ones, as long as the conditions of the BSD license are met.\n", + "\n", + "![border-image](_images/github_create_05.jpeg)" + ] + }, + { + "cell_type": "markdown", + "id": "4fc9305d-041b-45f5-942b-dd49ee83caca", + "metadata": {}, + "source": [ + "6. **Create Repository**:\n", + " - **Simple Process**: To create the repository, simply click on the \"Create repository\" button on GitHub.\n", + " - **User Action**: This action is typically the final step in the repository setup process and is straightforward to execute.\n", + "\n", + "![border-image](_images/github_create_06.jpeg)" + ] + }, + { + "cell_type": "markdown", + "id": "d47d9874-c305-4310-bee7-84c99fd71e8c", + "metadata": {}, + "source": [ + "7. **New Repository Configuration**:\n", + " - **Initial State**: Upon creation, the new repository will be empty but configured with the chosen `.gitignore` tailored for Python.\n", + " - **License File**: Additionally, a \"LICENSE\" file based on the BSD 2-Clause \"Simplified\" License will be included in the repository. This file is crucial for legally defining the terms under which your software can be used.\n", + "\n", + "![border-image](_images/github_create_07.png)" + ] + } + ], + "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 +} diff --git a/docs/source/notebooks/02-github_secrets.ipynb b/docs/source/notebooks/02-github_secrets.ipynb new file mode 100644 index 0000000..20360f9 --- /dev/null +++ b/docs/source/notebooks/02-github_secrets.ipynb @@ -0,0 +1,81 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "828afc51-716f-4b7f-9f31-188d36d30aee", + "metadata": {}, + "source": [ + "# Configuring Repository Variables and Secrets on GitHub\n", + "\n", + "In order to customize and secure your project environment, you need to set up variables and secrets within your GitHub repository. These are accessible in the repository settings under the `Settings` tab. Follow these steps to add the necessary variables:" + ] + }, + { + "cell_type": "markdown", + "id": "01736fb2-9418-47f3-943e-60bfafe3f6c2", + "metadata": {}, + "source": [ + "1. **Access Repository Settings**:\n", + " - Navigate to your GitHub repository page.\n", + " - Click on the `Settings` tab located at the top of the page.\n", + "\n", + "2. **Navigate to Secrets Section**:\n", + " - Within the `Settings` tab, scroll down to the `Secrets` section.\n", + " - Click on the `New repository secret` button to create a new secret.\n", + "\n", + "![border-image](_images/github_secrets_01.png)" + ] + }, + { + "cell_type": "markdown", + "id": "1b663dd7-794a-4bca-8838-6d262c76916a", + "metadata": {}, + "source": [ + "3. **Set Up Variables**:\n", + " - **Project Name**: Define the `DOCS_PROJECT_NAME` with the name of your project.\n", + " - **Author Name**: For `Name`, input `DOCS_AUTHOR`. For `Value`, enter the author's full name.\n", + " - **Author Email**: Add a new secret with `Name` as `DOCS_EMAIL` and the value as the author's email address.\n", + " - **Module**: Use `DOCS_MODULE` for the `Name` and the specific module name for the `Value`. Note that this should be the name of the repository.\n", + " - **Submodule**: If your project has submodules, use `DOCS_SUBMODULE` for the `Name` and the specific submodule name for the `Value`. This should also correspond to the name of the repository. For example, for a repository named `gcpds.docs`, `DOCS_MODULE` would be `gcpds` and `DOCS_SUBMODULE` would be `docs`.\n", + "\n", + "![border-image](_images/github_secrets_02.png)\n", + "\n", + "4. **Save Each Variable**:\n", + " - After entering the name and value for each variable, click the `Add secret` button to save it.\n", + "\n", + "5. **Review and Maintain Secrets**:\n", + " - Make sure to review your secrets and variables regularly.\n", + " - Update them as necessary to keep your environment secure and up to date." + ] + }, + { + "cell_type": "markdown", + "id": "27af9eff-bca7-4a04-bea1-ff7c7e1d1d7f", + "metadata": {}, + "source": [ + "Remember that secrets are encrypted environment variables created in your repository settings. They are not passed to workflows that are triggered by a pull request from a fork.\n" + ] + } + ], + "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 +} diff --git a/docs/source/notebooks/03-github_pat.ipynb b/docs/source/notebooks/03-github_pat.ipynb new file mode 100644 index 0000000..0ef8780 --- /dev/null +++ b/docs/source/notebooks/03-github_pat.ipynb @@ -0,0 +1,82 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0a78742a-47bd-472b-9d5f-958efe8d3eb2", + "metadata": {}, + "source": [ + "# Creating a Personal Access Token (Classic) on GitHub\n", + "\n", + "Personal Access Tokens (PATs) are used to grant applications, scripts, and command-line tools access to your GitHub resources. Follow the steps below to create a classic Personal Access Token with full permissions:" + ] + }, + { + "cell_type": "markdown", + "id": "a94c0263-2e20-4fb0-8cb6-3a0ba728a1d5", + "metadata": {}, + "source": [ + "1. **Access Developer Settings**:\n", + " - Go to your GitHub profile.\n", + " - Click on the avatar at the top right of any page.\n", + " - Choose `Settings` from the dropdown menu.\n", + " - On the settings page, look for the `Developer settings` section at the bottom of the left sidebar.\n", + "\n", + "2. **Personal Access Tokens**:\n", + " - Within `Developer settings`, select `Personal access tokens`.\n", + " - Click on the `Generate new token` button to create a new token.\n", + "\n", + "3. **Token Configuration**:\n", + " - Give your token a descriptive name in the `Note` field to remember the purpose of the token.\n", + " - Select the expiration date for the token as per your requirement.\n", + " - To grant full access, check all the boxes to enable all permissions for the token.\n", + "\n", + "![border-image](_images/github_pat_01.jpg) " + ] + }, + { + "cell_type": "markdown", + "id": "c69c60de-1876-4bfc-83d4-2cd32bcaa114", + "metadata": {}, + "source": [ + "4. **Generate and Save the Token**:\n", + " - Once you have configured the permissions, click the `Generate token` button at the bottom of the page.\n", + " - **Important**: As soon as the token is generated, make sure to copy and securely save it. **You won’t be able to see it again!** Losing this token requires generating a new one, and you must update all applications that use it.\n", + "\n", + "![border-image](_images/github_pat_02.png)\n", + " \n", + "5. **Storing the Token Securely**:\n", + " - Store the token in a secure location.\n", + " - Consider using a password manager or an encrypted storage solution to keep your token safe." + ] + }, + { + "cell_type": "markdown", + "id": "47663581-32c9-4b25-b0fe-53a70b612e28", + "metadata": {}, + "source": [ + "Remember, the Personal Access Token acts as a substitute for your GitHub password. Treat it as securely as you would your password, and never share it or commit it to your repositories." + ] + } + ], + "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 +} diff --git a/docs/source/notebooks/04-readthedocs.ipynb b/docs/source/notebooks/04-readthedocs.ipynb new file mode 100644 index 0000000..4f4bc89 --- /dev/null +++ b/docs/source/notebooks/04-readthedocs.ipynb @@ -0,0 +1,70 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "2cfcf414-368a-40ae-9a88-92c25850e46a", + "metadata": {}, + "source": [ + "# Creating a Project on Read the Docs\n", + "\n", + "Read the Docs automates the process of building and hosting your documentation. Here's how to get started with creating a new project:" + ] + }, + { + "cell_type": "markdown", + "id": "759db276-90ae-4a36-bab4-67a91243d022", + "metadata": {}, + "source": [ + "1. **Start a New Project**:\n", + " - Go to [Read the Docs](https://readthedocs.org/) and log in with your account.\n", + " - Click on the `Import a Project` button or navigate to the `Dashboard` and then `Import Project`.\n", + "\n", + "2. **Fill in Project Details**:\n", + " - **Name**: Enter the name of your project, such as `GCPDS - Docs`.\n", + " - **Repository URL**: Provide the URL of your GitHub repository where the documentation resides, like `https://github.com/UN-GCPD`.\n", + " - **Default Branch**: Specify the branch that Read the Docs should use to build your documentation, typically `main` or `master`.\n", + " - **Language**: Select the language in which your project documentation is written, for example, `English`.\n", + "\n", + "3. **Finalize and Build**:\n", + " - Click the `Next` button to proceed.\n", + " - Read the Docs will import your documentation from the specified repository and branch.\n", + " - After importing, Read the Docs will automatically build your documentation.\n", + "\n", + "![border-image](_images/readthedocs_01.png)\n", + "\n", + "5. **Review and Access Documentation**:\n", + " - Once the build process is complete, you can review your documentation by clicking on the link provided by Read the Docs.\n", + " - The link to your documentation is usually in the format `https://.readthedocs.io/`." + ] + }, + { + "cell_type": "markdown", + "id": "3338e5d0-34cd-4560-84db-c74f240fe542", + "metadata": {}, + "source": [ + "Remember to commit any changes you make to your documentation to your repository, which will trigger a new build on Read the Docs and update your hosted documentation accordingly." + ] + } + ], + "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 +} diff --git a/docs/source/notebooks/05-github_and_readthedocs.ipynb b/docs/source/notebooks/05-github_and_readthedocs.ipynb new file mode 100644 index 0000000..e501f3e --- /dev/null +++ b/docs/source/notebooks/05-github_and_readthedocs.ipynb @@ -0,0 +1,83 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "86265535-48c1-43a2-95a5-9fdd1486f750", + "metadata": {}, + "source": [ + "# Integrating GitHub with Webhooks for Read the Docs\n", + "\n", + "Webhooks allow your GitHub repository to communicate with external services like Read the Docs, triggering builds automatically every time you push changes. Here's how you can set up a webhook for your project:" + ] + }, + { + "cell_type": "markdown", + "id": "455984b1-c87a-45f9-b80d-6c452afe188d", + "metadata": {}, + "source": [ + "1. **Obtain Webhook Details from Read the Docs**:\n", + " - Go to your project on Read the Docs.\n", + " - Navigate to the `Admin` section.\n", + " - Click on `Integrations` from the sidebar menu.\n", + " - You will find a section titled 'Integration - GitHub incoming webhook' which contains the Webhook URL and a Secret. Copy these details as you will need them for the GitHub setup.\n", + " \n", + "![border-image](_images/webhook_01.png)\n", + "\n", + "2. **Configure Webhook on GitHub**:\n", + " - Access your GitHub repository.\n", + " - Click on the `Settings` tab.\n", + " - On the left sidebar, click on `Webhooks`, then on the `Add webhook` button.\n", + "\n", + "3. **Webhook Setup**:\n", + " - In the `Payload URL` field, paste the Webhook URL you copied from Read the Docs.\n", + " - For `Content type`, select `application/x-www-form-urlencoded`.\n", + " - In the `Secret` field, enter the Secret provided by Read the Docs.\n", + " - Enable SSL verification to ensure secure data transmission.\n", + "\n", + "4. **Select Trigger Events**:\n", + " - Choose which events you would like to trigger this webhook. Typically, you would select 'Just the push event' for documentation projects.\n", + "\n", + "5. **Activate Webhook**:\n", + " - Ensure the `Active` checkbox is selected to enable the webhook.\n", + " - Click on `Add webhook` to save and activate the webhook.\n", + " \n", + "![border-image](_images/webhook_02.png)\n", + "\n", + "6. **Verify Webhook Integration**:\n", + " - Once the webhook is added, GitHub will send a ping to Read the Docs to test the connection.\n", + " - You can verify the integration by pushing a commit to your repository and checking if a new build is triggered on Read the Docs.\n", + " \n", + "![border-image](_images/webhook_03.png)" + ] + }, + { + "cell_type": "markdown", + "id": "6aab566f-2bdf-4f63-9130-56925350d319", + "metadata": {}, + "source": [ + "**Important**: Remember to save your webhook settings on GitHub immediately after adding them. The secret token is sensitive information and should be kept secure. Also, GitHub will not display the secret again after you navigate away from the page." + ] + } + ], + "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 +} diff --git a/docs/source/notebooks/06-repository_structure_setup.ipynb b/docs/source/notebooks/06-repository_structure_setup.ipynb new file mode 100644 index 0000000..8ce4c00 --- /dev/null +++ b/docs/source/notebooks/06-repository_structure_setup.ipynb @@ -0,0 +1,217 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "09acbb5e-3b8c-4805-bcab-1089c0c4e873", + "metadata": {}, + "source": [ + "# Repository Structure Setup" + ] + }, + { + "cell_type": "markdown", + "id": "f28e0d8b-7fdf-4d87-9e56-dd86bb9cd196", + "metadata": {}, + "source": [ + "## Setting Up the Repository with Git\n", + "\n", + "The following instructions will guide you through the process of setting up the initial folder structure for your repository based on the previously defined DOCS_MODULE and DOCS_SUBMODULE variables." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "444cd5b7-e986-4e0b-8c50-95d302d59d1f", + "metadata": {}, + "outputs": [], + "source": [ + "# Clone the repository to your local machine\n", + "git clone https://github.com/your-username/your-repository.git\n", + "\n", + "# Navigate to the repository's directory\n", + "cd your-repository\n", + "\n", + "# Create a new directory with the name of your module\n", + "mkdir $DOCS_MODULE\n", + "\n", + "# Navigate into the newly created module directory\n", + "cd $DOCS_MODULE\n", + "\n", + "# Within the module directory, create a subdirectory for the submodule\n", + "mkdir $DOCS_SUBMODULE\n", + "\n", + "# Add the new directory structure to your repository\n", + "git add .\n", + "\n", + "# Commit the changes with a descriptive message\n", + "git commit -m \"Set up initial directory structure for DOCS_MODULE and DOCS_SUBMODULE\"\n", + "\n", + "# Push the changes to the remote repository\n", + "git push origin main" + ] + }, + { + "cell_type": "markdown", + "id": "77721db5-6087-4f92-af67-bcebbc0de37e", + "metadata": {}, + "source": [ + "Replace `path/to/your/project` with the actual path to your project's root directory. The `$DOCS_MODULE` and `$DOCS_SUBMODULE` should be replaced with the actual names you have assigned to your repository variables. This will create a hierarchy of directories reflecting the module and submodule structure of your project.\n", + "\n", + "Ensure that you replace the placeholders with the actual values for `DOCS_MODULE` and `DOCS_SUBMODULE` when executing these commands. These placeholders correspond to the names you defined in the [Configuring Repository Variables and Secrets on GitHub](02-github_secrets.ipynb) section." + ] + }, + { + "cell_type": "markdown", + "id": "ebbf1eb7-f608-4c83-aa5d-b0a65ddc4170", + "metadata": {}, + "source": [ + "## Writing Your Python Module\n", + "\n", + "Creating a Python module involves writing a Python script with functions, classes, or variables. Here's a basic guide on how to create a simple Python module.\n", + "\n", + "1. **Create a Python File**: \n", + " - Create a new file with a `.py` extension within your `DOCS_MODULE` or `DOCS_SUBMODULE` directory.\n", + " - For example, if creating a module named `example`, your file would be `example.py`.\n", + "\n", + "2. **Writing Module Content**:\n", + " - Open the file in a text editor or an IDE.\n", + " - Start defining your functions, classes, or variables.\n", + "\n", + "3. **Example Python Module**:\n", + " - Below is a basic example of a Python module that contains a simple function.\n", + " \n", + "```python\n", + "# example.py\n", + "\n", + "def greet(name):\n", + " \"\"\"\n", + " This function greets the person whose name is passed as a parameter\n", + " \"\"\"\n", + " return f\"Hello, {name}!\"\n", + "\n", + "if __name__ == \"__main__\":\n", + " print(greet(\"World\"))\n", + "```\n", + "\n", + "4. **Using the Module**:\n", + " - You can use this module by importing it into other Python scripts.\n", + " - Here is an example of how to import and use the `greet` function from the `example.py` module.\n", + "\n", + "```python\n", + "# another_script.py\n", + "\n", + "from example import greet\n", + "\n", + "print(greet(\"User\"))\n", + "```\n", + "\n", + "This is a basic template for creating a Python module. You can expand it with more complex functionality, classes, and error handling as needed for your project. Remember to follow good coding practices, such as clear commenting and consistent naming conventions, to ensure your code is easily understandable and maintainable." + ] + }, + { + "cell_type": "markdown", + "id": "1aed5fcf-f518-4e48-865a-f878c76eb085", + "metadata": {}, + "source": [ + "## Module Directory Structure\n", + "\n", + "Below is the structure of the directories and subdirectories for the `DOCS_MODULE` and `DOCS_SUBMODULE`. This structure should be reflected in your local repository after executing the Git commands to set up the initial folders:\n", + "\n", + "```plaintext\n", + "your-repository/\n", + "└── DOCS_MODULE/\n", + " └── DOCS_SUBMODULE/\n", + " ├── file1.py\n", + " ├── file2.py\n", + " └── subfolder/\n", + " └── file3.py\n", + "```\n", + "\n", + "In this structure:\n", + "- `your-repository` is the root of your cloned repository.\n", + "- `DOCS_MODULE` is the main module directory.\n", + "- `DOCS_SUBMODULE` is a submodule within `DOCS_MODULE`.\n", + "- `file1.py`, `file2.py`, and `file3.py` represent Python script files.\n", + "- `subfolder` is an additional subdirectory within `DOCS_SUBMODULE` containing `file3.py`.\n", + "\n", + "Replace `DOCS_MODULE` and `DOCS_SUBMODULE` with the actual names you have chosen for your module and submodule. This tree structure provides a visual representation of how your files and folders are organized within the repository." + ] + }, + { + "cell_type": "markdown", + "id": "7ddfb65b-015a-4ef9-9283-bd7d130d52dd", + "metadata": {}, + "source": [ + "## Configuring Workflows in GitHub\n", + "\n", + "Workflows in GitHub Actions automate your development process. They can be used for a variety of tasks, such as testing code, building artifacts, and deploying applications. To set up workflows, you need to create a specific directory structure in your repository.\n", + "\n", + "### Creating the Workflow Directory\n", + "\n", + "Follow these steps to create a `.github/workflows` directory in your repository, which is where your workflow files will reside:\n", + "\n", + "```bash\n", + "# Navigate to your repository's root directory\n", + "cd path/to/your-repository\n", + "\n", + "# Create the .github directory if it does not exist\n", + "mkdir -p .github\n", + "\n", + "# Within the .github directory, create the workflows directory\n", + "cd .github\n", + "mkdir workflows\n", + "\n", + "# Your directory structure should now look like this:\n", + "# your-repository/\n", + "# └── .github/\n", + "# └── workflows/\n", + "```\n", + "\n", + "Replace `path/to/your-repository` with the actual path to your repository's root directory. This structure is a standard convention in GitHub Actions and is necessary for GitHub to recognize and execute your workflows.\n", + "\n", + "### Adding Workflow Files\n", + "\n", + "After creating the directory structure, you can add workflow files (YAML files) into the `.github/workflows` directory. These files define your workflows and the conditions under which they should run. For example, you might have a workflow for automated testing and another for building documentation.\n", + "\n", + "```plaintext\n", + "# Example of a basic workflow file structure\n", + "your-repository/\n", + "└── .github/\n", + " └── workflows/\n", + " ├── automated-setup.yml\n", + " └── automated-sphinx-docs.yml\n", + "```\n", + "\n", + "You will be using two workflow files:\n", + "\n", + "1. **`automated-setup.yml`**: This workflow automatically creates the `setup.py` file for your Python project.\n", + "2. **`automated-sphinx-docs.yml`**: This workflow sets up a Sphinx environment automatically for your documentation.\n", + "\n", + "In this example, `automated-setup.yml` could be a workflow for setting up your project environment, and `automated-sphinx-docs.yml` could be for building and deploying Sphinx documentation.\n", + "\n", + "Remember, the workflow files must be written in YAML format and correctly configured to match your project's needs. The specific contents of these files will depend on the tasks you want to automate." + ] + } + ], + "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 +} diff --git a/docs/source/notebooks/_images/github_create.jpeg b/docs/source/notebooks/_images/github_create.jpeg new file mode 100644 index 0000000..21daa2d Binary files /dev/null and b/docs/source/notebooks/_images/github_create.jpeg differ diff --git a/docs/source/notebooks/_images/github_create_01.jpeg b/docs/source/notebooks/_images/github_create_01.jpeg new file mode 100644 index 0000000..de87b35 Binary files /dev/null and b/docs/source/notebooks/_images/github_create_01.jpeg differ diff --git a/docs/source/notebooks/_images/github_create_02.jpeg b/docs/source/notebooks/_images/github_create_02.jpeg new file mode 100644 index 0000000..619fd11 Binary files /dev/null and b/docs/source/notebooks/_images/github_create_02.jpeg differ diff --git a/docs/source/notebooks/_images/github_create_03.jpeg b/docs/source/notebooks/_images/github_create_03.jpeg new file mode 100644 index 0000000..9e213e9 Binary files /dev/null and b/docs/source/notebooks/_images/github_create_03.jpeg differ diff --git a/docs/source/notebooks/_images/github_create_04.jpeg b/docs/source/notebooks/_images/github_create_04.jpeg new file mode 100644 index 0000000..a7b785f Binary files /dev/null and b/docs/source/notebooks/_images/github_create_04.jpeg differ diff --git a/docs/source/notebooks/_images/github_create_05.jpeg b/docs/source/notebooks/_images/github_create_05.jpeg new file mode 100644 index 0000000..9f438f4 Binary files /dev/null and b/docs/source/notebooks/_images/github_create_05.jpeg differ diff --git a/docs/source/notebooks/_images/github_create_06.jpeg b/docs/source/notebooks/_images/github_create_06.jpeg new file mode 100644 index 0000000..5858950 Binary files /dev/null and b/docs/source/notebooks/_images/github_create_06.jpeg differ diff --git a/docs/source/notebooks/_images/github_create_07.png b/docs/source/notebooks/_images/github_create_07.png new file mode 100644 index 0000000..a7f79bf Binary files /dev/null and b/docs/source/notebooks/_images/github_create_07.png differ diff --git a/docs/source/notebooks/_images/github_pat_01.jpg b/docs/source/notebooks/_images/github_pat_01.jpg new file mode 100644 index 0000000..aea3aa8 Binary files /dev/null and b/docs/source/notebooks/_images/github_pat_01.jpg differ diff --git a/docs/source/notebooks/_images/github_pat_02.png b/docs/source/notebooks/_images/github_pat_02.png new file mode 100644 index 0000000..fc1a0b1 Binary files /dev/null and b/docs/source/notebooks/_images/github_pat_02.png differ diff --git a/docs/source/notebooks/_images/github_secrets_01.png b/docs/source/notebooks/_images/github_secrets_01.png new file mode 100644 index 0000000..bfdea32 Binary files /dev/null and b/docs/source/notebooks/_images/github_secrets_01.png differ diff --git a/docs/source/notebooks/_images/github_secrets_02.png b/docs/source/notebooks/_images/github_secrets_02.png new file mode 100644 index 0000000..ddbc6d2 Binary files /dev/null and b/docs/source/notebooks/_images/github_secrets_02.png differ diff --git a/docs/source/notebooks/_images/github_secrets_and_variables.jpeg b/docs/source/notebooks/_images/github_secrets_and_variables.jpeg new file mode 100644 index 0000000..7bee3a0 Binary files /dev/null and b/docs/source/notebooks/_images/github_secrets_and_variables.jpeg differ diff --git a/docs/source/notebooks/_images/readthedocs_01.png b/docs/source/notebooks/_images/readthedocs_01.png new file mode 100644 index 0000000..0f10202 Binary files /dev/null and b/docs/source/notebooks/_images/readthedocs_01.png differ diff --git a/docs/source/notebooks/_images/webhook_01.png b/docs/source/notebooks/_images/webhook_01.png new file mode 100644 index 0000000..6f7a99f Binary files /dev/null and b/docs/source/notebooks/_images/webhook_01.png differ diff --git a/docs/source/notebooks/_images/webhook_02.png b/docs/source/notebooks/_images/webhook_02.png new file mode 100644 index 0000000..8373329 Binary files /dev/null and b/docs/source/notebooks/_images/webhook_02.png differ diff --git a/docs/source/notebooks/_images/webhook_03.png b/docs/source/notebooks/_images/webhook_03.png new file mode 100644 index 0000000..207353c Binary files /dev/null and b/docs/source/notebooks/_images/webhook_03.png differ diff --git a/docs/source/notebooks/readme.ipynb b/docs/source/notebooks/readme.ipynb new file mode 100644 index 0000000..3bbde25 --- /dev/null +++ b/docs/source/notebooks/readme.ipynb @@ -0,0 +1,113 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0", + "metadata": {}, + "source": [ + "# GCPDS - Documentation Guide\n", + "\n", + "Welcome to the \"GCPDS - Documentation Guide\". This guide serves as a comprehensive resource for setting up, configuring, and maintaining the documentation of projects under the General Computational Perception and Decision Systems (GCPDS) initiative. Our goal is to standardize the process of documentation across various modules and projects to enhance clarity, accessibility, and ease of use.\n", + "\n", + "The guide outlines a series of steps and best practices aimed at ensuring a seamless integration of Python modules with version control and automated documentation systems. By following these guidelines, developers and contributors will be able to maintain a high standard of code management and documentation, which is vital for collaborative development and the long-term success of the project.\n", + "\n", + "We cover everything from the initial setup of a GitHub repository, including naming conventions and configuration, to the integration with Read the Docs for automated documentation generation. Additionally, we discuss security practices, such as handling sensitive data through repository secrets and access tokens, to ensure the integrity and confidentiality of the project.\n", + "\n", + "Each section of this guide is designed to walk you through the necessary steps to achieve an efficient and secure workflow. By adhering to these guidelines, the GCPDS community can contribute to a robust and sustainable ecosystem for research and development in computational perception and decision systems." + ] + }, + { + "cell_type": "markdown", + "id": "9a5ddb18-a2f1-45b7-a96d-da6a7037cd71", + "metadata": {}, + "source": [ + "## Installation Instructions\n", + "\n", + "To integrate the `gcpds.docs` module into your Python environment, the process is straightforward and managed via `pip`, Python's package installer. Ensure that you have `pip` installed and that it is up to date to avoid any compatibility issues. Follow the command below to install the latest version of `gcpds.docs`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "48311743-1136-4b5d-956c-97f8c2468686", + "metadata": {}, + "outputs": [], + "source": [ + "pip install -U gcpds.docs" + ] + }, + { + "cell_type": "markdown", + "id": "bf88d02c-600c-4d0c-b080-6135fc7f1980", + "metadata": {}, + "source": [ + "This command will download and install the `gcpds.docs` module along with its dependencies. The `-U` flag ensures that if the package is already installed, it will be upgraded to the latest version.\n", + "\n", + "After the installation is complete, you can import and use `gcpds.docs` in your Python projects to enhance your documentation process.\n", + "\n", + "**Note:** It is recommended to perform this installation within a virtual environment to maintain a clean workspace and avoid version conflicts with other projects." + ] + }, + { + "cell_type": "markdown", + "id": "f2af4a5b-aa0f-477a-987a-7f541f1a766f", + "metadata": { + "jp-MarkdownHeadingCollapsed": true + }, + "source": [ + "## Introduction to Setting Up and Integrating a Python Module Repository\n", + "\n", + "This documentation provides a structured approach to setting up a Python module repository on GitHub and integrating it with external documentation and automation services. The objective is to streamline the process of repository management, code security, and documentation generation for Python projects. By following these guidelines, developers can ensure their projects are well-organized, secure, and easily maintainable.\n", + "\n", + "### Objectives\n", + "\n", + "1. **Establish Conventions**: Define a clear and descriptive naming convention for Python module repositories to maintain consistency and clarity across projects.\n", + " \n", + "2. **Secure Configuration**: Implement repository variables and secrets to manage environment configurations and sensitive information securely.\n", + " \n", + "3. **Access Management**: Generate a Personal Access Token (Classic) to provide secure access to GitHub resources, enabling automated processes and integrations.\n", + " \n", + "4. **Documentation Automation**: Create and configure a project on Read the Docs to facilitate automatic generation and hosting of project documentation.\n", + " \n", + "5. **Continuous Integration**: Set up webhooks between GitHub and Read the Docs to enable real-time documentation updates with each code commit, ensuring the latest project changes are always documented.\n", + "\n", + "By adhering to these steps, we aim to create a robust workflow that encapsulates best practices for repository setup, security, and documentation, while also leveraging automation to reduce manual effort and potential errors.\n", + "\n", + "### Steps Overview\n", + "\n", + "- **Guidelines for Python Module Repository Naming and Configuration on GitHub**: This section will guide you through the best practices for naming your Python module repository, setting it to public, and choosing the appropriate license.\n", + "\n", + "- **Configuring Repository Variables and Secrets on GitHub**: Here, you will learn how to securely store and manage environment-specific configurations within your GitHub repository settings.\n", + "\n", + "- **Creating a Personal Access Token (Classic) on GitHub**: This part of the documentation explains the process of creating a Personal Access Token to interact with GitHub's API securely.\n", + "\n", + "- **Creating a Project on Read the Docs**: We will go through the steps of setting up your project on Read the Docs, ensuring your documentation is automatically generated from your repository.\n", + "\n", + "- **Integrating GitHub with Webhooks for Read the Docs**: Lastly, you will set up a webhook to connect your GitHub repository with Read the Docs, allowing for automated documentation builds upon every commit.\n", + "\n", + "Following these guidelines will set a solid foundation for your Python projects on GitHub and ensure that your documentation is always up-to-date with your latest code changes." + ] + } + ], + "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 +} diff --git a/docs/source/notebooks/readme.rst b/docs/source/notebooks/readme.rst new file mode 100644 index 0000000..8d10a82 --- /dev/null +++ b/docs/source/notebooks/readme.rst @@ -0,0 +1,121 @@ +GCPDS - Documentation Guide +=========================== + +Welcome to the “GCPDS - Documentation Guide”. This guide serves as a +comprehensive resource for setting up, configuring, and maintaining the +documentation of projects under the General Computational Perception and +Decision Systems (GCPDS) initiative. Our goal is to standardize the +process of documentation across various modules and projects to enhance +clarity, accessibility, and ease of use. + +The guide outlines a series of steps and best practices aimed at +ensuring a seamless integration of Python modules with version control +and automated documentation systems. By following these guidelines, +developers and contributors will be able to maintain a high standard of +code management and documentation, which is vital for collaborative +development and the long-term success of the project. + +We cover everything from the initial setup of a GitHub repository, +including naming conventions and configuration, to the integration with +Read the Docs for automated documentation generation. Additionally, we +discuss security practices, such as handling sensitive data through +repository secrets and access tokens, to ensure the integrity and +confidentiality of the project. + +Each section of this guide is designed to walk you through the necessary +steps to achieve an efficient and secure workflow. By adhering to these +guidelines, the GCPDS community can contribute to a robust and +sustainable ecosystem for research and development in computational +perception and decision systems. + +Installation Instructions +------------------------- + +To integrate the ``gcpds.docs`` module into your Python environment, the +process is straightforward and managed via ``pip``, Python’s package +installer. Ensure that you have ``pip`` installed and that it is up to +date to avoid any compatibility issues. Follow the command below to +install the latest version of ``gcpds.docs``: + +.. code:: ipython3 + + pip install -U gcpds.docs + +This command will download and install the ``gcpds.docs`` module along +with its dependencies. The ``-U`` flag ensures that if the package is +already installed, it will be upgraded to the latest version. + +After the installation is complete, you can import and use +``gcpds.docs`` in your Python projects to enhance your documentation +process. + +**Note:** It is recommended to perform this installation within a +virtual environment to maintain a clean workspace and avoid version +conflicts with other projects. + +Introduction to Setting Up and Integrating a Python Module Repository +--------------------------------------------------------------------- + +This documentation provides a structured approach to setting up a Python +module repository on GitHub and integrating it with external +documentation and automation services. The objective is to streamline +the process of repository management, code security, and documentation +generation for Python projects. By following these guidelines, +developers can ensure their projects are well-organized, secure, and +easily maintainable. + +Objectives +~~~~~~~~~~ + +1. **Establish Conventions**: Define a clear and descriptive naming + convention for Python module repositories to maintain consistency and + clarity across projects. + +2. **Secure Configuration**: Implement repository variables and secrets + to manage environment configurations and sensitive information + securely. + +3. **Access Management**: Generate a Personal Access Token (Classic) to + provide secure access to GitHub resources, enabling automated + processes and integrations. + +4. **Documentation Automation**: Create and configure a project on Read + the Docs to facilitate automatic generation and hosting of project + documentation. + +5. **Continuous Integration**: Set up webhooks between GitHub and Read + the Docs to enable real-time documentation updates with each code + commit, ensuring the latest project changes are always documented. + +By adhering to these steps, we aim to create a robust workflow that +encapsulates best practices for repository setup, security, and +documentation, while also leveraging automation to reduce manual effort +and potential errors. + +Steps Overview +~~~~~~~~~~~~~~ + +- **Guidelines for Python Module Repository Naming and Configuration on + GitHub**: This section will guide you through the best practices for + naming your Python module repository, setting it to public, and + choosing the appropriate license. + +- **Configuring Repository Variables and Secrets on GitHub**: Here, you + will learn how to securely store and manage environment-specific + configurations within your GitHub repository settings. + +- **Creating a Personal Access Token (Classic) on GitHub**: This part + of the documentation explains the process of creating a Personal + Access Token to interact with GitHub’s API securely. + +- **Creating a Project on Read the Docs**: We will go through the steps + of setting up your project on Read the Docs, ensuring your + documentation is automatically generated from your repository. + +- **Integrating GitHub with Webhooks for Read the Docs**: Lastly, you + will set up a webhook to connect your GitHub repository with Read the + Docs, allowing for automated documentation builds upon every commit. + +Following these guidelines will set a solid foundation for your Python +projects on GitHub and ensure that your documentation is always +up-to-date with your latest code changes. diff --git a/docs/source/notebooks/run.sh b/docs/source/notebooks/run.sh new file mode 100755 index 0000000..c6f9b03 --- /dev/null +++ b/docs/source/notebooks/run.sh @@ -0,0 +1,5 @@ +#!/usr/bin/bash + +source /home/yeison/Development/venv/sphinx/bin/activate +jupyter lab --notebook-dir='.' + diff --git a/gcpds/docs/__init__.py b/gcpds/docs/__init__.py new file mode 100644 index 0000000..be0b527 --- /dev/null +++ b/gcpds/docs/__init__.py @@ -0,0 +1,438 @@ +""" +====================================================================== +GitHub Integration and Workflow Management with Jupyter and ipywidgets +====================================================================== + +This module provides a user-friendly graphical interface in Jupyter notebooks for managing GitHub repositories. It uses +ipywidgets to create an interactive environment for seamless integration with GitHub. The functionalities include cloning, +committing, pulling, pushing, and checking the status of the repositories, along with managing GitHub Actions workflows. + +Subsections +----------- +- Widgets: Custom ipywidgets classes for text validation, buttons, and command layout interfaces. +- GitHubLazy: Core class with methods to interact with GitHub repositories and manage workflows. +- Interface Layout: Helper function to create and display the ipywidgets interface layout. + +""" + +import os +import sys +import shutil +import logging +import subprocess +from pathlib import Path +from typing import Optional, Callable + +import ipywidgets as widgets +from IPython.display import display, HTML + +try: + from google.colab.userdata import get as get_secret + WORKING_PATH: Path = Path('/').joinpath('content').resolve() + REPOSITORY_PATH: Path = Path( + '/').joinpath('content', 'my_repository').resolve() +except: + from ipython_secrets import get_secret, delete_secret + WORKING_PATH: Path = Path('.').resolve() + REPOSITORY_PATH: Path = Path('.').joinpath('my_repository').resolve() + +WORKFLOW_DIR = REPOSITORY_PATH / '.github' / 'workflows' +CURRENT_DIR = Path(__file__).parent + + +######################################################################## +class ValidateText(widgets.Text): + """ + A custom widget class that extends ipywidgets.Text to include validation functionality. + + Attributes: + button (widgets.Button): A button widget that changes based on the validation. + + Methods: + _update_style(change): Updates the button style based on validation conditions. + """ + + # ---------------------------------------------------------------------- + def __init__(self, **kwargs): + """ + Initialize the ValidateText widget. + + Args: + validate (bool): A flag to activate validation. + button (widgets.Button): A button widget linked to this text widget. + """ + super().__init__(**kwargs) + self.validate: bool = kwargs.get('validate', False) + self.button: widgets.Button = kwargs.get('button', None) + + if self.validate: + self.observe(self._update_style, names='value') + + # ---------------------------------------------------------------------- + def _update_style(self, change: dict) -> None: + """ + Update the style of the associated button based on the validation condition. + + Args: + change (dict): A dictionary containing the change details. + """ + new_value = change['new'] + cond = bool(new_value) if self.validate is True else new_value.startswith( + self.validate) + + self.button.button_style = 'success' if cond else 'danger' + self.button.disabled = not cond + + +######################################################################## +class CustomButton(widgets.Button): + """ + A custom button widget with predefined layout and optional callback functionality. + + Methods: + __init__(callback): Initializes the custom button with a callback function. + """ + + # ---------------------------------------------------------------------- + def __init__(self, callback: Optional[Callable] = None, **kwargs): + """ + Initialize the CustomButton widget. + + Args: + callback (Callable, optional): The function to call when the button is clicked. + """ + super().__init__(**kwargs) + self.layout = widgets.Layout( + height='37px', width=kwargs.get('width', 'none')) + + if callback: + self.on_click(callback) + + +######################################################################## +class CommandLayout: + """ + A layout class combining a text widget with a custom button for command inputs. + + Methods: + __init__(description, button, callback, placeholder, validate): Initializes the command layout. + layout: Returns the widget layout. + text: Gets or sets the text value of the text widget. + """ + + # ---------------------------------------------------------------------- + def __init__(self, description: str, button: str, callback: Optional[Callable] = None, + placeholder: str = '', validate: bool = False, tooltip: str = ''): + """ + Initialize the CommandLayout with a text widget and a button. + + Args: + description (str): The description for the text widget. + button (str): The label for the button. + callback (Callable, optional): The function to call when the button is clicked. + placeholder (str): Placeholder text for the text widget. + validate (bool): Whether to enable validation on the text widget. + """ + self.button = CustomButton( + description=button, button_style='danger', disabled=True, tooltip=tooltip) + self.validate_text = ValidateText( + placeholder=placeholder, + description=description, + disabled=False, + validate=validate, + button=self.button, + layout=widgets.Layout(width='100%', padding='5px') + ) + + if callback: + self.button.on_click(callback) + + # ---------------------------------------------------------------------- + @property + def layout(self) -> widgets.AppLayout: + """ + Get the widget layout for the command layout. + + Returns: + widgets.AppLayout: The layout combining the text widget and the button. + """ + return widgets.AppLayout(center=self.validate_text, right_sidebar=self.button) + + # ---------------------------------------------------------------------- + @property + def text(self) -> str: + """ + Get the current text value of the text widget. + + Returns: + str: The current text value. + """ + return self.validate_text.value + + # ---------------------------------------------------------------------- + @text.setter + def text(self, value: str) -> None: + """ + Set the text value of the text widget. + + Args: + value (str): The text value to set. + """ + self.validate_text.value = value + + +######################################################################## +class GitHubLazy: + """ + A class for managing GitHub operations within a Jupyter notebook environment using ipywidgets. + + This class provides functionalities to clone, commit, pull, push, and check the status of a GitHub repository. + """ + + GITHUB_PAT: Optional[str] = get_secret('GITHUB_PAT') + GITHUB_NAME: Optional[str] = get_secret('GITHUB_NAME') + GITHUB_EMAIL: Optional[str] = get_secret('GITHUB_EMAIL') + + logger: widgets.Label = widgets.Label( + '', layout=widgets.Layout(font_family='monospace', font_size='20px')) + logger.add_class('lab-logger') + + # ---------------------------------------------------------------------- + def __init__(self): + """Initializes the GitHubLazy interface with necessary widgets and configurations.""" + + self.github_title = widgets.Label( + "GitHub Integration for Jupyter: Simplified Management") + self.github_title.add_class('title-size') + + self.github_header = widgets.Label("This tool is an integrated system for managing GitHub repositories within a Jupyter Notebook environment. It offers a user-friendly graphical interface that simplifies common Git operations, making them more accessible to users of all skill levels.", + # layout=widgets.Layout(height='100px'), + ) + self.github_header.add_class('text-wrap') + + self.clone_layout = CommandLayout('Repository', 'Clone', callback=self.clone, + placeholder='https://github.com//.git', + validate='https://github.com/', + tooltip="Creates a local copy of a remote repository. This command is used to download existing source code from a remote repository to a local machine.", + ) + self.commit_layout = CommandLayout('Message', 'Commit', callback=self.commit, + placeholder='Update', + validate=True, + tooltip="Records changes made to files in a local repository. A commit saves a snapshot of the project's currently staged changes.", + ) + + self.status_button = CustomButton(description='Status', button_style='info', callback=self.status, + tooltip="Displays the state of the working directory and the staging area. It shows which changes have been staged, which haven't, and which files aren't being tracked by Git.") + self.pull_button = CustomButton(description='Pull', button_style='info', callback=self.pull, + tooltip="Fetches changes from a remote repository and merges them into the local branch. This is used to update the local code with changes from others.") + self.push_button = CustomButton(description='Push', button_style='warning', callback=self.push, + tooltip="Updates the remote repository with any commits made locally to a branch. It's a way to share your changes with others.") + + self.github_button_layout = widgets.HBox([self.status_button, self.pull_button, self.push_button], + layout=widgets.Layout(justify_content='flex-start', width='100%')) + + yml_files = [] + for yml_file in CURRENT_DIR.glob('*.yml'): + checkbox = widgets.Checkbox(value=(WORKFLOW_DIR / yml_file.name).exists(), + description=yml_file.name, + disabled=False, + indent=True, + layout=widgets.Layout(width='90%'), + ) + checkbox.observe(lambda evt, yml_file=yml_file: self.copy_workflow( + yml_file), names='value') + yml_files.append(checkbox) + + if yml_files: + self.webhooks_title = widgets.Label( + "Automated Workflow Creation for GitHub Repositories") + self.webhooks_title.add_class('title-size') + self.right_button_layout = widgets.VBox( + yml_files, layout=widgets.Layout(justify_content='flex-start', width='100%')) + + self.run_command( + f'git config --global user.name "{self.GITHUB_NAME}"', silent=True) + self.run_command( + f'git config --global user.email "{self.GITHUB_EMAIL}"', silent=True) + + # ---------------------------------------------------------------------- + def run_command(self, command: str, path: str = '.', silent: bool = True) -> None: + """ + Executes a given shell command in the specified directory path. + + Args: + command (str): The shell command to execute. + path (str): The directory path where the command is to be executed. + silent (bool): If True, suppresses the logging output. + """ + original_dir = os.getcwd() + os.chdir(path) + + if not silent: + logging.warning(f'Original directory: {original_dir}') + logging.warning(f'Moving to {path}') + logging.warning(f'Running command: {command}') + + result = subprocess.run( + command, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) + + stdout, stderr = result.stdout, result.stderr + self.logger.value = f'{stdout}\n{stderr}' + + os.chdir(original_dir) + + if not silent: + logging.warning(f'Back again to {original_dir}') + + # ---------------------------------------------------------------------- + def clone(self, evt: Optional[widgets.Button] = None) -> None: + """ + Clones a GitHub repository based on the URL provided in the clone_layout text widget. + + Parameters + ---------- + evt : Optional[widgets.Button], optional + The button event that triggers this method (default is None). + + """ + repository_url = self.clone_layout.text.removeprefix('https://') + self.run_command( + f"git clone https://{self.GITHUB_PAT}@{repository_url} my_repository", path=WORKING_PATH) + self.run_command('git config pull.rebase true', silent=True) + self.run_command( + 'git config --global credential.helper cache', silent=True) + sys.path.append(REPOSITORY_PATH) + + # ---------------------------------------------------------------------- + def commit(self, evt: Optional[widgets.Button] = None) -> None: + """ + Commits changes to the local repository with the message provided in the commit_layout text widget. + + Parameters + ---------- + evt : Optional[widgets.Button], optional + The button event that triggers this method (default is None). + + """ + self.run_command("git add .", path=REPOSITORY_PATH) + self.run_command("git add -f .github", path=REPOSITORY_PATH) + self.run_command( + f"git commit -m '{self.commit_layout.text.strip()}'", path=REPOSITORY_PATH) + self.commit_layout.text = '' + + # ---------------------------------------------------------------------- + def pull(self, evt: Optional[widgets.Button] = None) -> None: + """ + Pulls the latest changes from the remote repository. + + Parameters + ---------- + evt : Optional[widgets.Button], optional + The button event that triggers this method (default is None). + + """ + self.run_command('git config pull.rebase true', silent=True) + self.run_command("git pull", path=REPOSITORY_PATH) + + # ---------------------------------------------------------------------- + def status(self, evt: Optional[widgets.Button] = None) -> None: + """ + Checks the current status of the local repository. + + Parameters + ---------- + evt : Optional[widgets.Button], optional + The button event that triggers this method (default is None). + + """ + self.run_command("git status", path=REPOSITORY_PATH) + + # ---------------------------------------------------------------------- + def push(self, evt: Optional[widgets.Button] = None) -> None: + """ + Pushes local commits to the remote repository. + + Parameters + ---------- + evt : Optional[widgets.Button], optional + The button event that triggers this method (default is None). + + """ + self.run_command("git push", path=REPOSITORY_PATH) + + # ---------------------------------------------------------------------- + def copy_workflow(self, workflow: Path) -> None: + """ + Copies the specified GitHub Actions workflow file to the repository's workflow directory. + + Parameters + ---------- + workflow : Path + Path object representing the workflow file to be copied. + + """ + os.makedirs(WORKFLOW_DIR, exist_ok=True) + workflow_docs_dst = REPOSITORY_PATH / '.github' / 'workflows' / workflow.name + if workflow_docs_dst.exists(): + os.remove(workflow_docs_dst) + else: + shutil.copyfile(workflow, workflow_docs_dst) + + +# ---------------------------------------------------------------------- +def delete_secrets() -> None: + """ + Removes saved GitHub secrets from storage. + + This method deletes the saved GitHub Personal Access Token, GitHub + username, and GitHub email address from secure credential storage. + """ + delete_secret('GITHUB_PAT') + delete_secret('GITHUB_NAME') + delete_secret('GITHUB_EMAIL') + + +# ---------------------------------------------------------------------- +def __lab__() -> widgets.GridspecLayout: + """ + Creates and displays a GitHub management interface using ipywidgets. + + This function initializes the GitHubLazy class and arranges its components into a GridspecLayout for display. + + Returns: + widgets.GridspecLayout: A grid layout containing the GitHubLazy interface components. + """ + + lab = GitHubLazy() + + # Define the layout components + layouts = [ + lab.github_title, + lab.github_header, + ] + + if not REPOSITORY_PATH.exists(): + layouts.append(lab.clone_layout.layout) + else: + layouts.extend([ + lab.commit_layout.layout, + lab.github_button_layout, + ]) + + layouts.extend([ + lab.webhooks_title, + lab.right_button_layout, + lab.logger, + ]) + + # Apply CSS styles to the logger + display(HTML( + '')) + display(HTML( + '')) + display( + HTML('')) + + grid = widgets.VBox(layouts, layout=widgets.Layout( + justify_content='flex-start', width='100%')) + return grid diff --git a/workflows/automated-setup.yml b/workflows/automated-setup.yml new file mode 100644 index 0000000..cbd032c --- /dev/null +++ b/workflows/automated-setup.yml @@ -0,0 +1,65 @@ +# .github/workflows + +name: Automated Setup Generation + +# Workflow triggers +on: + workflow_dispatch: # Allows manual triggering of the workflow + push: # Triggers the workflow on every push to the repository + +jobs: + format-code-customized: + runs-on: ubuntu-latest # Specifies the virtual machine to use, in this case, the latest version of Ubuntu + + # Defines permissions for this job + permissions: + contents: write # Permissions to write to the repository + + steps: + - uses: actions/checkout@v4 # Checks out the code from the repository + + # Step to update and prepare the documentation + - name: Prepare and Update Documentation + + run: | + # Verifica si setup.py existe, si no, lo crea + if [ ! -f "setup.py" ]; then + echo """import os + from setuptools import setup + + with open(os.path.join(os.path.dirname(__file__), 'README.md')) as readme: + README = readme.read() + + os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir))) + + setup( + name=\"${{ vars.MODULE }}\", + version='0.1', + packages=[\"${{ vars.MODULE }}\"], + author=\"${{ vars.AUTHOR }}\", + author_email=\"${{ vars.EMAIL }}\", + maintainer=\"${{ vars.AUTHOR }}\", + maintainer_email=\"${{ vars.EMAIL }}\", + download_url='', + install_requires=[ + ], + scripts=[ + ], + include_package_data=True, + license='Simplified BSD License', + description=\"\", + zip_safe=False, + long_description=README, + long_description_content_type='text/markdown', + python_requires='>=3.7', + + #https://pypi.org/classifiers/ + classifiers=[ + ], + ) + """ >> setup.py + fi + + + # Commit all changed files back to the repository + - uses: stefanzweifel/git-auto-commit-action@v5 diff --git a/workflows/automated-sphinx-docs.yml b/workflows/automated-sphinx-docs.yml new file mode 100644 index 0000000..40194ff --- /dev/null +++ b/workflows/automated-sphinx-docs.yml @@ -0,0 +1,82 @@ +# .github/workflows + +name: Automated Documentation and Code Formatting + +# Workflow triggers +on: + workflow_dispatch: # Allows manual triggering of the workflow + push: # Triggers the workflow on every push to the repository + +jobs: + format-code-customized: + runs-on: ubuntu-latest # Specifies the virtual machine to use, in this case, the latest version of Ubuntu + + # Defines permissions for this job + permissions: + contents: write # Permissions to write to the repository + + steps: + - uses: actions/checkout@v4 # Checks out the code from the repository + + # Step to update and prepare the documentation + - name: Prepare and Update Documentation + + run: | + # Pulls necessary Docker images for documentation + docker pull dunderlab/docs + docker pull sphinxdoc/sphinx-latexpdf + + # Installs required Python packages + pip install nbsphinx + pip install dunderlab-docs + + # Sets up initial documentation if a 'docs' directory does not exist + if [ ! -d "docs" ]; then + dunderlab_docs quickstart '--project "${{ vars.PROJECT_NAME }}" --author "${{ vars.AUTHOR }}" --extensions nbsphinx,dunderlab.docs --no-batchfile --quiet --sep' + fi + + # Generates API documentation and builds HTML and Latex PDF if SUBMODULE is set + if [ -n "${{ vars.SUBMODULE }}" ]; then + dunderlab_docs apidoc "${{ vars.MODULE }}" + dunderlab_docs build html "${{ vars.MODULE }}/${{ vars.SUBMODULE }}" + dunderlab_docs build latexpdf "${{ vars.MODULE }}/${{ vars.SUBMODULE }}" + else + dunderlab_docs apidoc "${{ vars.MODULE }}" + dunderlab_docs build html "${{ vars.MODULE }}" + dunderlab_docs build latexpdf "${{ vars.MODULE }}" + fi + + # Adds a configuration file for Read the Docs + # Verifies if .readthedocs.yml exists, if not, creates it + if [ ! -f ".readthedocs.yml" ]; then + echo """# .readthedocs.yml + # Read the Docs configuration file + # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + + # Required + version: 2 + + # Build documentation in the docs/ directory with Sphinx + sphinx: + configuration: docs/source/conf.py + + # Optionally set the version of Python and requirements required to build your docs + python: + install: + - requirements: docs/requirements + + # Set the version of Python and other tools you might need + build: + os: ubuntu-22.04 + tools: + python: \"3.11\" + + formats: + - epub + - pdf + """ >> .readthedocs.yml + fi + + + # Commit all changed files back to the repository + - uses: stefanzweifel/git-auto-commit-action@v5