A template repository to test and document elements and features for research software. It implements the collection of repository elements and files. The goal is to simplify and standardise the creation of software in GitHub repositories.
"},{"location":"#documentation-structure","title":"Documentation Structure","text":"The documentation is separated into two main sections: Development and Code Documentation.
"},{"location":"#fields-for-development","title":"Fields for development","text":"Files and structures related to collaborative development, community processes, and documentation.
Methods and functions of the module.
Adopting best practices in software development enhances code quality, maintains consistency, and ensures reliability. This section focuses on three key methodologies essential for maintaining high standards in a collaborative scientific software environment:
Continuous Integration (CI): Automating the integration of code changes to catch errors early and maintain a stable codebase. CI ensures that all contributions are rigorously tested and integrated seamlessly into the project.
Test-Driven Development (TDD): A methodology where tests are written before the actual code implementation. TDD promotes robust and well-designed code by enforcing that each feature is accompanied by thorough testing from the outset.
Pre-commit Hooks (PCH): Tools to enforce code quality and consistency by running checks or scripts before changes are committed. These hooks help identify issues early, improving code hygiene and reducing technical debt.
Following these practices will streamline development, reduce bugs, and foster a productive, collaborative coding environment.
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/best-practice/code_style/","title":"Code Style","text":"This document aims to provide clear instructions on how to write clean, readable, and maintainable Python code. Adhering to these guidelines will ensure consistency across the codebase and foster collaboration among contributors. Maintaining a consistent code style is crucial for the readability and maintainability of a Python project.
We enforce most of the following guidelines in our Continuous-Integration pipeline that check the code automatically.
"},{"location":"development/best-practice/code_style/#1-installation","title":"1. Installation","text":"Before contributing to the project, make sure you have the necessary tools installed for code style enforcement. We utilize pre-commit to automate code checks before committing changes.
"},{"location":"development/best-practice/code_style/#2-code-formatting","title":"2. Code Formatting","text":"Consistent code formatting enhances readability and reduces unnecessary debates about style. We use Ruff as Python code formatter. It automatically formats your code to adhere to the project's style guidelines.
"},{"location":"development/best-practice/code_style/#3-naming-conventions","title":"3. Naming Conventions","text":"While we don't enforce strict naming conventions, we encourage compliance with PEP8 and the Google Python Style Guide for consistency. Descriptive names and adherence to conventions improve code clarity.
"},{"location":"development/best-practice/code_style/#4-indentation-and-whitespace","title":"4. Indentation and Whitespace","text":"We follow the Python standard of using 4 spaces for tab indentation. Do not include any trailing whitespace at the end of lines.
"},{"location":"development/best-practice/code_style/#5-comments-and-documentation","title":"5. Comments and Documentation","text":"Effective comments and docstrings are vital for code understanding. Use comments to explain complex logic and docstrings to describe functions, classes, and modules. Following good documentation practices ensures code is understandable to others.
"},{"location":"development/best-practice/code_style/#6-code-structure-and-organization","title":"6. Code Structure and Organization","text":"Maintain a logical structure within files, grouping related functions and classes. Consider the readability of your code and strive for modular, well-organized files.
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/best-practice/continuous_integration/","title":"Continuous Integration (CI) and Test Automation","text":"Continuous Integration (CI) ensures consistent code quality through automated testing, reporting, and deployments. Our setup combines GitHub Actions and tox to streamline testing across environments, making the process robust and efficient.
GitHub Actions automates key workflows like testing, linting, and code quality checks. The CI pipeline includes the following tasks: - Unit Testing: Using pytest to ensure comprehensive test coverage. - Code Formatting: Validating syntax with ruff. - Linting: Verifying code style and docstrings with ruff.lint. - Import Sorting: Organizing imports with ruff.lint.isort.
To set up GitHub Actions workflows for the repository, follow the official GitHub guide. The GitHub Actions workflow is triggered on pull requests or commits to the develop or production branches. 1. Setup: Prepares a Python environment and installs dependencies. 2. Testing: Executes the tox automation suite to run the defined tests. 3. Reporting: Generates detailed failure reports for debugging.
GitHub Actions also automates documentation updates, ensuring the latest changes from the develop branch are reflected. For more details, see the official GitHub Actions guide.
tox is a versatile tool for managing test environments and automating testing tasks across Python versions and operating systems (Linux, macOS, Windows). It enhances reproducibility and reliability by creating isolated environments for testing:
pytest, ruff). tox.ini. Install the required package in a python environment. \ud83d\udcbb pip install tox Install tox \ud83d\udcbb tox Run tox locally
New tests should be placed in the \ud83d\udcdd test/ directory. For example: - Add a test to validate new functionality. - Use pytest for unit tests, or extend \ud83d\udcdd tox.ini for additional test configurations.
By combining tox and GitHub Actions, our CI pipeline ensures robust, reproducible, and scalable testing workflows.
unittest, pytestExample: Simple function test and external API interactions.
Functional Testing
pytest, seleniumExample: Test user login in a web app.
Mocking
unittest.mock, pytest-mockExample: Mock API calls in tests.
Acceptance Testing
pytest, BehaveExample: Verify login form functionality.
Performance Testing
pytest-benchmark, locustExample: Measure function execution time.
Security Testing
banditSnapshot Testing
pytest-snapshotProperty-Based Testing
hypothesisThe file \ud83d\udcdd test/test_example.py contains basic examples for the functions in \ud83d\udcdd super_repo/test_calculator.py.
In Python, the assert statement is used to test if a condition is true. If the condition is false, an AssertionError is raised, indicating the test failed.
result = add(3, 4)\nassert result == 7\nThe raises context manager from the pytest library ensures that a ValueError is raised. The match argument specifies that the error message matches the expected error pattern.
with raises(ValueError, match=r\"Cannot divide by zero\"):\n divide(15, 0)\nWe encourage contributions of additional tests and examples to help improve coverage and showcase different use cases\u2014your input is valuable to enhancing the project!
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/best-practice/pre_commit_hooks/","title":"Pre-commit Hooks","text":"Pre-commit hooks are tools used to enforce code quality and consistency by running checks or scripts before changes are committed. These hooks help identify issues early, improving code hygiene.
"},{"location":"development/best-practice/pre_commit_hooks/#installation-and-setup","title":"Installation and Setup","text":"Install the package in your base environment. \ud83d\udcbb pip install pre-commit
Create a \ud83d\udcdd .pre-commit-config.yaml file in your repository root. This file defines the hooks and configurations.
To run the hooks manually, use: \ud83d\udcbb pre-commit run --all-files
Now, every time you commit changes, the pre-commit hooks will automatically run the checks defined in your configuration file, ensuring code quality before committing.
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/best-practice/test_driven_development/","title":"Test-Driven Development","text":"Test-Driven Development (TDD) is a software development methodology that emphasizes writing tests before implementing the corresponding functionality. This approach ensures that new changes do not unintentionally break existing features and that all functions perform as expected.
"},{"location":"development/best-practice/test_driven_development/#code-coverage","title":"Code Coverage","text":"Code coverage is a metric used in software testing that helps determine the percentage of code that is exercised by tests. It is an essential tool for assessing the effectiveness of your test suite. High code coverage generally indicates that most of your code has been tested, while lower coverage can suggest that some parts of the application may be under-tested, potentially leading to hidden bugs or vulnerabilities.
Codecov.io is a popular tool for tracking and visualizing code coverage. It integrates with various CI/CD pipelines and allows developers to upload their coverage reports. Once integrated, Codecov provides detailed insights into code coverage trends, coverage gaps, and areas that require further testing.
To integrate Codecov with your project, follow these steps:
Install pytest \ud83d\udcbb pip install pytest pytest-cov
Add GitHub Action \ud83d\udcdd .github/workflows/codecov.yml
Create an account Create a Codecov account at Codecov.io and link your repository.
Upload the Coverage Report After running your tests with coverage, upload the results to Codecov. This is done automatically through the CI configuration.
View Coverage Reports Once your coverage report is uploaded, you can view detailed insights and trends on the Codecov dashboard.
Code Coverage Badge A coverage badge provides a visual indication of the test coverage for the \ud83d\udcdd README.rst page. It is updated automatically as new reports are uploaded to Codecov.
While code coverage is a valuable metric for identifying untested code, high coverage does not necessarily indicate high-quality tests. It only measures the quantity of code exercised during testing, not the quality or effectiveness of those tests. Tests can pass without actually verifying correct behavior, and some areas of the code may be covered by trivial tests that do not expose potential issues. Relying solely on coverage can lead to a false sense of security and might divert attention from other important aspects of testing, such as edge cases and integration scenarios.
"},{"location":"development/best-practice/test_driven_development/#example-implementing-test-cases-for-a-django-app","title":"Example: Implementing Test Cases for a Django App","text":"This example demonstrates the TDD approach within a Django app. You can run all tests in Django using the following command:
\ud83d\udcbb `python manage.py test`\nTo run specific test cases, you can provide the app name and the test case:
\ud83d\udcbb `python manage.py test app.MyModelViewTestCase`\nThis is a Step-by-Step Guide to TDD in Django:
"},{"location":"development/best-practice/test_driven_development/#1-set-up-the-django-app","title":"1. Set Up the Django App","text":"Ensure that you have a Django app in place that you wish to test.
"},{"location":"development/best-practice/test_driven_development/#2-write-a-test-for-the-new-feature","title":"2. Write a Test for the New Feature","text":"Begin by writing a test for the functionality you intend to implement. For example, if you need to create a view that returns a list of objects from the database, and a corresponding model to represent the database table, your test might look like this: \ud83d\udcdd app/test/my_test.py:
from django.test import TestCase\nfrom myapp.models import MyModel\n\nclass MyModelViewTestCase(TestCase):\n def test_list_view_displays_all_objects(self):\n MyModel.objects.create(name=\"object1\")\n MyModel.objects.create(name=\"object2\")\n response = self.client.get('/my-models/')\n self.assertEqual(response.status_code, 200)\n self.assertContains(response, \"object1\")\n self.assertContains(response, \"object2\")\nAt this point, run the test to confirm it fails, as the view has not been implemented yet. \ud83d\udcbb python manage.py test
Implement the model and view to make the test pass.
\ud83d\udcdd models.py:
from django.db import models\n\nclass MyModel(models.Model):\n name = models.CharField(max_length=255)\n created_at = models.DateTimeField(auto_now_add=True)\n\n def __str__(self):\n return self.name\n\ud83d\udcdd views.py:
from django.views.generic import ListView\nfrom myapp.models import MyModel\n\nclass MyModelListView(ListView):\n model = MyModel\n template_name = \"myapp/my_model_list.html\"\nRun the tests again to ensure the changes pass the test. \ud83d\udcbb python manage.py test
Write additional tests to verify that the view works as expected. For example, you can test for empty responses:
class MyModelViewTestCase(TestCase):\n def test_list_view_displays_all_objects(self):\n MyModel.objects.create(name=\"object1\")\n MyModel.objects.create(name=\"object2\")\n response = self.client.get('/my-models/')\n self.assertEqual(response.status_code, 200)\n self.assertContains(response, \"object1\")\n self.assertContains(response, \"object2\")\n\n def test_list_view_displays_empty_message(self):\n response = self.client.get('/my-models/')\n self.assertEqual(response.status_code, 200)\n self.assertContains(response, \"No objects found.\")\nFinally, run all the tests to ensure they pass successfully: \ud83d\udcbb python manage.py test
TDD provides a structured approach to writing reliable, maintainable software. By ensuring that tests are written before implementing functionality, developers can be confident that new changes will not introduce unintended side effects and that the codebase remains functional and robust over time.
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/collaboration/","title":"Collaboration","text":"This open-source software is a collaborative effort. The repository has several elements to provide necessary functions.
To participate in the development you can do the following:
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/collaboration/chat/","title":"Chat","text":"For direct communication, this repository uses a public Element room. This messenger platform is based on the [matrix] communication protocol and can be accessed without a mobile phone.
To engage with the developer and user community, login with an existing account (for example GitHub) or register a new account.
The room name is: Super-Repository:matrix.org.
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/collaboration/code_of_conduct/","title":"Code of Conduct","text":"This repository is following the Contributor Covenant Code of Conduct.
Everyone is asked to be self-reflective and always maintain a good culture of discussion and active participation. This includes written communication in this repository and direct encounters in meetings and events.
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/collaboration/git/","title":"Git","text":""},{"location":"development/collaboration/git/#branches","title":"Branches","text":"Git Branches are used to structure the developments and improvements.
"},{"location":"development/collaboration/git/#permanent-branches","title":"Permanent Branches","text":"The majority of the development will be done in feature branches.
This file specifies intentionally untracked files to ignore. It is copied from a collection of .gitignore templates. For more information about how \ud83d\udcdd .gitignore files work, see the Ignoring Files chapter of the Pro Git book.
Issue Templates offer specific functions and default configurations for new issues.
The Pull Request Template is used for all PR, because it is only possible to create a single one. It includes all needed information to merge branches and release new versions.
"},{"location":"development/collaboration/git/#github-labels","title":"GitHub Labels","text":"GitHub Labels are used to organize Issues and PR. Colours and emoticons improve presentation, see: \ud83d\udcdd github-labels.json
"},{"location":"development/collaboration/git/#github-workflows-actions","title":"GitHub Workflows (Actions)","text":"GitHub Actions are used to automate processes of the repository. Main use-cases are building and publishing the documentation and run automated tests.
"},{"location":"development/collaboration/git/#pre-commit","title":"Pre-commit","text":"Pre-commit is a tool to easily setup and run pre-commit hooks for your git repository. See the best-practice documentation of pre-commit or the official documentation for further information. It is used to improve auto-format code, do linting and run tests before every commit.
Install the required package in a python environment. \ud83d\udcbb pip install pre-commit Install pre-commit \ud83d\udcbb pre-commit install Install pre-commit
The hooks are configured in the file \ud83d\udcdd .pre-commit-config.yaml. List of implemented hooks:
All commits will trigger the hooks automatically. \ud83d\udca0 git commit file -m \"Commit message #IssueNr\" Commit with message
Commit without running the hooks. \ud83d\udca0 git commit --no-verify file Commit without hooks
Line endings
There can be problems with file line endings on Windows, CRLF is used on Windows and LF is used on Linux.
To run the hooks on all files in your repository use: \ud83d\udcbb pre-commit run --all-files Run pre-commit hooks
Markdown files / Admonitions
If the hook is applied to markdown files that include special formatting, (for example \ud83d\udcdd mkdocs.yml), this can introduce incorrect changes. This effects admonitions boxes for MkDocs.
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/collaboration/license_and_citation/","title":"License","text":""},{"location":"development/collaboration/license_and_citation/#software-license","title":"Software License","text":"This software is developed under an open-source license. The selected license can be read in the LICENSE.txt.
The users have permission to run and use, modify, distribute the program, and release the improvements as long as you follow the license obligations to give a proper attribution and include the license text.
Please attribute as:
\"Super-Repository\" \u00a9 Reiner Lemoine Institut | MIT License
"},{"location":"development/collaboration/license_and_citation/#reuse","title":"REUSE","text":"This repository follows the REUSE SOFTWARE specification. All files are explicitly stating the corresponding license and copyright information. It is implemented as GitHub workflow and pre-commit hook:
All copyright information should follow this example:
SPDX-FileCopyrightText: {$year_of_file_creation} {$name_of_author} <{contact}> \u00a9 {$name_of_copyright_holder}\nSPDX-FileCopyrightText: {$year_of_file_creation} {$name_of_author2} <{contact2}> \u00a9 {$name_of_copyright_holder2}\n\nSPDX-License-Identifier: {$SPDX_license_name}\nTo scientifically cite this repository, see the Cite this repository function or the file CITATION.cff.
"},{"location":"development/collaboration/license_and_citation/#contributing","title":"Contributing","text":"Since this software is under an open source license and can be downloaded, run and modified, you are invited to comment, improve and develop the program as you wish. To contribute to the collaborative development follow the workflow described in CONTRIBUTING.md.
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/collaboration/meeting/","title":"Meetings","text":"In order to develop a program collaboratively, it is helpful to regularly exchange information about the current status and to discuss open questions and make decisions. If you want to join the meetings, please use the GitHub Discussions.
"},{"location":"development/collaboration/meeting/#developer-meetings","title":"Developer Meetings","text":"In the regular developer meetings, the open issues and pull requests are discussed and the next release is planned. There should also be time for the general vision of software development.
The regular developer meeting takes place on the first Wednesday of the month between 9 and 9:30 am. The meeting room is: meet.jit.si/super-repo-dev
"},{"location":"development/collaboration/meeting/#user-meetings","title":"User Meetings","text":"The user meeting is specifically designed for users of the software to ask questions about usage, make requests for new functionality, or give general feedback.
The regular user meeting takes place after the developer meeting in the same room on the first Wednesday of the month between 9:30 and 10 am.
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/collaboration/users/","title":"Users","text":"Known user of this software can be added to \ud83d\udcdd USERS.cff for reference. Please use the issue template: \ud83d\udcdd issue_template_user_kudos.md
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/documentation/","title":"Documentation","text":""},{"location":"development/documentation/#readme","title":"README","text":"The repository contains a \ud83d\udcdd README.rst file with basic information. It gives a short introduction to the project and links to other relevant files.
The \ud83d\udcdd CHANGELOG.md is a record of all notable changes made to a project. It is structured by each release and divided by additions, changes, and removals.
MkDocs is a fast and simple static site generator that is used for documentation. The source files are written in Markdown, and configured with \ud83d\udcdd mkdocs.yml. Material theme enables additional features and an elegant design.
Install the required packages in a python environment. \ud83d\udcbb pip install mkdocs Install MkDocs \ud83d\udcbb pip install mkdocs-material Install the material theme
Generate the documentation locally. \ud83d\udcbb mkdocs serve Start the local live version of the documentation \ud83d\udcbb mkdocs build Create a folder site with the documentation
Publish documentation on GitHub Pages. \ud83d\udcbb mkdocs gh-deploy Manually deploys the documentation files
Manually deploy documentation
This command overrides all manually deployed versions (mike).
"},{"location":"development/documentation/#github-action","title":"GitHub Action","text":"\ud83d\udc19 Deploy the documentation with GitHub Actions. The file \ud83d\udcdd .github\\workflows\\documentation.yml creates an automated GitHub workflow. It is configured to be pushed to the branch gh-page and then deployed online. A commit on the develop branch starts the workflow.
The package mike is used to deploy multiple versions of the documentation. \ud83d\udcbb pip install mike Install mike \ud83d\udcbb mike deploy --push --update-aliases 0.1 latest Deploys the latest version \ud83d\udcbb mike set-default --push latest Set the default version to latest \ud83d\udcbb mike deploy develop --push Deploys the develop branch
Mike Versions
It is recommended to use only the Minor Versions (for example 0.1) and exclude the Patch Version (for example 0.1.1)!
Other useful commands are: \ud83d\udcbb mike serve Test mike on http://localhost:8000 \ud83d\udcbb mike list List all versions \ud83d\udcbb mike retitle 1.0.0 1.0.1 --push Rename a version \ud83d\udcbb mike delete 0.1 --push Deletes a specific versions \ud83d\udcbb mike delete --all --push Deletes all versions
When adding older versions, load the Git Tags used for the releases: \ud83d\udca0 git checkout v0.1.1 \ud83d\udcbb mike deploy 0.1 --push Deploys the old version 0.1
When building mike locally, the branch gh-pages is modified locally. \ud83d\udcbb error: gh-pages is unrelated to origin/gh-pages \ud83d\udca0 git branch -D gh-pages Delete the local documentation branch
mkdocstrings generates automatic documentation (autodocs) from Google style docstrings. \ud83d\udcbb pip install mkdocstrings Install mkdocstrings
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"development/release/","title":"Release","text":"The software release has four main goals:
production branchThe \ud83d\udcdd RELEASE_PROCEDURE.md contain detailed instructions to do a release.
"},{"location":"development/release/#automated-versioning-with-bumpversion","title":"Automated Versioning with Bumpversion","text":"Bumpversion is a tool for automated version management in software projects. It ensures consistent version updates across files and documentation by specifying a part to increment (major, minor, or patch). This streamlines release workflows and keeps project versioning synchronized.
Install package: \ud83d\udcbb pip install --upgrade bump-my-version \ud83d\udcdd .bumpversion.toml Configuration file for versioning rules and affected files
Test bumpversion: \ud83d\udcbb bump-my-version show-bump Preview next possible versions \ud83d\udcbb bump-my-version bump minor --dry-run -vv Sandbox bump
Use bumpversion: \ud83d\udcbb bump-my-version bump --current-version 0.2.0 minor Run bumpversion \ud83d\udca0 git push Push bumpversion changes
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"},{"location":"user_documentation/","title":"Functions","text":"mkdocstrings
This software uses mkdocstings to render docstrings from files.
The code documentation is implemented by writing docstrings. See the mkdocstrings documentation.
"},{"location":"user_documentation/code_example/","title":"Code Example","text":"About the example
Below you see the rendered version of the example module super_repo\\example_google.py
Example Google style docstrings.
SPDX-FileCopyrightText: Copyright (c) 2007-2023 by the Sphinx team SPDX-License-Identifier: BSD-2-Clause
https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html
This module demonstrates documentation as specified by the Google Python Style Guide_. Docstrings may extend over multiple lines. Sections are created with a section header and a colon followed by a block of indented text.
Examples:
Examples can be given using either the Example or Examples sections. Sections support any reStructuredText formatting, including literal blocks::
$ python example_google.py\nSection breaks are created by resuming unindented text. Section breaks are also implicitly created anytime a new section starts.
Attributes:
Name Type Descriptionmodule_level_variable1 int Module level variables may be documented in either the Attributes section of the module docstring, or in an inline docstring immediately following the variable.
Either form is acceptable, but the two should not be mixed. Choose one convention to document module level variables and be consistent with it.
Todo:
* For module TODOs\n* You have to also use ``sphinx.ext.todo`` extension\n.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
"},{"location":"user_documentation/code_example/#super_repo.example_google.module_level_variable2","title":"module_level_variable2","text":"int: Module level variable documented inline.
The docstring may span multiple lines. The type may optionally be specified on the first line, separated by a colon.
"},{"location":"user_documentation/code_example/#super_repo.example_google.ExampleClass","title":" ExampleClass ","text":"The summary line for a class docstring should fit on one line.
If the class has public attributes, they may be documented here in an Attributes section and follow the same formatting as a function's Args section. Alternatively, attributes may be documented inline with the attribute's declaration (see init method below).
Properties created with the @property decorator should be documented in the property's getter method.
Attributes:
Name Type Descriptionattr1 str Description of attr1.
attr2 obj:int, optional): Description of attr2.
super_repo/example_google.py class ExampleClass:\n \"\"\"The summary line for a class docstring should fit on one line.\n\n If the class has public attributes, they may be documented here\n in an ``Attributes`` section and follow the same formatting as a\n function's ``Args`` section. Alternatively, attributes may be documented\n inline with the attribute's declaration (see __init__ method below).\n\n Properties created with the ``@property`` decorator should be documented\n in the property's getter method.\n\n Attributes:\n attr1 (str): Description of `attr1`.\n attr2 (:obj:`int`, optional): Description of `attr2`.\n\n \"\"\"\n\n def __init__(self, param1, param2, param3):\n \"\"\"Example of docstring on the __init__ method.\n\n The __init__ method may be documented in either the class level\n docstring, or as a docstring on the __init__ method itself.\n\n Either form is acceptable, but the two should not be mixed. Choose one\n convention to document the __init__ method and be consistent with it.\n\n Note:\n Do not include the `self` parameter in the ``Args`` section.\n\n Args:\n param1 (str): Description of `param1`.\n param2 (:obj:`int`, optional): Description of `param2`. Multiple\n lines are supported.\n param3 (:obj:`list` of :obj:`str`): Description of `param3`.\n\n \"\"\"\n self.attr1 = param1\n self.attr2 = param2\n self.attr3 = param3 #: Doc comment *inline* with attribute\n\n #: list of str: Doc comment *before* attribute, with type specified\n self.attr4 = [\"attr4\"]\n\n self.attr5 = None\n \"\"\"str: Docstring *after* attribute, with type specified.\"\"\"\n\n @property\n def readonly_property(self):\n \"\"\"str: Properties should be documented in their getter method.\"\"\"\n return \"readonly_property\"\n\n @property\n def readwrite_property(self):\n \"\"\":obj:`list` of :obj:`str`: Properties with both a getter and setter.\n\n (should only be documented in their getter method)\n\n If the setter method contains notable behavior, it should be\n mentioned here.\n \"\"\"\n return [\"readwrite_property\"]\n\n @readwrite_property.setter\n def readwrite_property(self, value):\n value\n\n def example_method(self, param1, param2):\n \"\"\"\n Class methods are similar to regular functions.\n\n Note:\n Do not include the `self` parameter in the ``Args`` section.\n\n Args:\n param1: The first parameter.\n param2: The second parameter.\n\n Returns:\n True if successful, False otherwise.\n\n \"\"\"\n return True\n\n def __special__(self):\n \"\"\"By default special members with docstrings are not included.\n\n Special members are any methods or attributes that start with and\n end with a double underscore. Any special member with a docstring\n will be included in the output, if\n ``napoleon_include_special_with_doc`` is set to True.\n\n This behavior can be enabled by changing the following setting in\n Sphinx's conf.py::\n\n napoleon_include_special_with_doc = True\n\n \"\"\"\n pass\n\n def __special_without_docstring__(self):\n pass\n\n def _private(self):\n \"\"\"By default private members are not included.\n\n Private members are any methods or attributes that start with an\n underscore and are *not* special. By default they are not included\n in the output.\n\n This behavior can be changed such that private members *are* included\n by changing the following setting in Sphinx's conf.py::\n\n napoleon_include_private_with_doc = True\n\n \"\"\"\n pass\n\n def _private_without_docstring(self):\n pass\nreadonly_property property readonly","text":"str: Properties should be documented in their getter method.
"},{"location":"user_documentation/code_example/#super_repo.example_google.ExampleClass.readwrite_property","title":"readwrite_property property writable","text":":obj:list of :obj:str: Properties with both a getter and setter.
(should only be documented in their getter method)
If the setter method contains notable behavior, it should be mentioned here.
"},{"location":"user_documentation/code_example/#super_repo.example_google.ExampleClass.__init__","title":"__init__(self, param1, param2, param3) special","text":"Example of docstring on the init method.
The init method may be documented in either the class level docstring, or as a docstring on the init method itself.
Either form is acceptable, but the two should not be mixed. Choose one convention to document the init method and be consistent with it.
Note
Do not include the self parameter in the Args section.
Parameters:
Name Type Description Defaultparam1 str Description of param1.
param2 obj:int, optional): Description of param2. Multiple lines are supported.
param3 obj:list of :obj:str): Description of param3.
super_repo/example_google.py def __init__(self, param1, param2, param3):\n \"\"\"Example of docstring on the __init__ method.\n\n The __init__ method may be documented in either the class level\n docstring, or as a docstring on the __init__ method itself.\n\n Either form is acceptable, but the two should not be mixed. Choose one\n convention to document the __init__ method and be consistent with it.\n\n Note:\n Do not include the `self` parameter in the ``Args`` section.\n\n Args:\n param1 (str): Description of `param1`.\n param2 (:obj:`int`, optional): Description of `param2`. Multiple\n lines are supported.\n param3 (:obj:`list` of :obj:`str`): Description of `param3`.\n\n \"\"\"\n self.attr1 = param1\n self.attr2 = param2\n self.attr3 = param3 #: Doc comment *inline* with attribute\n\n #: list of str: Doc comment *before* attribute, with type specified\n self.attr4 = [\"attr4\"]\n\n self.attr5 = None\n \"\"\"str: Docstring *after* attribute, with type specified.\"\"\"\n__special__(self) special","text":"By default special members with docstrings are not included.
Special members are any methods or attributes that start with and end with a double underscore. Any special member with a docstring will be included in the output, if napoleon_include_special_with_doc is set to True.
This behavior can be enabled by changing the following setting in Sphinx's conf.py::
napoleon_include_special_with_doc = True\nsuper_repo/example_google.py def __special__(self):\n \"\"\"By default special members with docstrings are not included.\n\n Special members are any methods or attributes that start with and\n end with a double underscore. Any special member with a docstring\n will be included in the output, if\n ``napoleon_include_special_with_doc`` is set to True.\n\n This behavior can be enabled by changing the following setting in\n Sphinx's conf.py::\n\n napoleon_include_special_with_doc = True\n\n \"\"\"\n pass\nexample_method(self, param1, param2)","text":"Class methods are similar to regular functions.
Note
Do not include the self parameter in the Args section.
Parameters:
Name Type Description Defaultparam1 The first parameter.
requiredparam2 The second parameter.
requiredReturns:
Type DescriptionTrue if successful, False otherwise.
Source code insuper_repo/example_google.py def example_method(self, param1, param2):\n \"\"\"\n Class methods are similar to regular functions.\n\n Note:\n Do not include the `self` parameter in the ``Args`` section.\n\n Args:\n param1: The first parameter.\n param2: The second parameter.\n\n Returns:\n True if successful, False otherwise.\n\n \"\"\"\n return True\n ExampleError (Exception) ","text":"Exceptions are documented in the same way as classes.
The init method may be documented in either the class level docstring, or as a docstring on the init method itself.
Either form is acceptable, but the two should not be mixed. Choose one convention to document the init method and be consistent with it.
Note
Do not include the self parameter in the Args section.
Parameters:
Name Type Description Defaultmsg str Human readable string describing the exception.
requiredcode obj:int, optional): Error code.
Attributes:
Name Type Descriptionmsg str Human readable string describing the exception.
code int Exception error code.
Source code insuper_repo/example_google.py class ExampleError(Exception):\n \"\"\"Exceptions are documented in the same way as classes.\n\n The __init__ method may be documented in either the class level\n docstring, or as a docstring on the __init__ method itself.\n\n Either form is acceptable, but the two should not be mixed. Choose one\n convention to document the __init__ method and be consistent with it.\n\n Note:\n Do not include the `self` parameter in the ``Args`` section.\n\n Args:\n msg (str): Human readable string describing the exception.\n code (:obj:`int`, optional): Error code.\n\n Attributes:\n msg (str): Human readable string describing the exception.\n code (int): Exception error code.\n\n \"\"\"\n\n def __init__(self, msg, code):\n self.msg = msg\n self.code = code\nexample_generator(n)","text":"Generators have a Yields section instead of a Returns section.
Parameters:
Name Type Description Defaultn int The upper limit of the range to generate, from 0 to n - 1.
Yields:
Type Descriptionint The next number in the range of 0 to n - 1.
Examples:
Examples should be written in doctest format, and should illustrate how to use the function.
>>> print([i for i in example_generator(4)])\n[0, 1, 2, 3]\nsuper_repo/example_google.py def example_generator(n):\n \"\"\"Generators have a ``Yields`` section instead of a ``Returns`` section.\n\n Args:\n n (int): The upper limit of the range to generate, from 0 to `n` - 1.\n\n Yields:\n int: The next number in the range of 0 to `n` - 1.\n\n Examples:\n Examples should be written in doctest format, and should illustrate how\n to use the function.\n\n >>> print([i for i in example_generator(4)])\n [0, 1, 2, 3]\n\n \"\"\"\n for i in range(n):\n yield i * i\nfunction_with_pep484_type_annotations(param1, param2)","text":"Example function with PEP 484 type annotations.
Parameters:
Name Type Description Defaultparam1 int The first parameter.
requiredparam2 str The second parameter.
requiredReturns:
Type Descriptionbool The return value. True for success, False otherwise.
Source code insuper_repo/example_google.py def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:\n \"\"\"Example function with PEP 484 type annotations.\n\n Args:\n\n param1: The first parameter.\n param2: The second parameter.\n\n Returns:\n\n The return value. True for success, False otherwise.\n\n \"\"\"\n return True\nfunction_with_types_in_docstring(param1, param2)","text":"Example function with types documented in the docstring.
PEP 484 type annotations are supported. If attribute, parameter, and return types are annotated according to PEP 484, they do not need to be included in the docstring:
Parameters:
Name Type Description Defaultparam1 int The first parameter.
requiredparam2 str The second parameter.
requiredReturns:
Type Descriptionbool The return value. True for success, False otherwise.
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/\nsuper_repo/example_google.py def function_with_types_in_docstring(param1, param2):\n \"\"\"Example function with types documented in the docstring.\n\n `PEP 484`_ type annotations are supported. If attribute, parameter, and\n return types are annotated according to `PEP 484`_, they do not need to be\n included in the docstring:\n\n Args:\n\n param1 (int): The first parameter.\n param2 (str): The second parameter.\n\n Returns:\n\n bool: The return value. True for success, False otherwise.\n\n .. _PEP 484:\n\n https://www.python.org/dev/peps/pep-0484/\n\n \"\"\"\nmodule_level_function(param1, param2=None, *args, **kwargs)","text":"This is an example of a module level function.
Function parameters should be documented in the Args section. The name of each parameter is required. The type and description of each parameter is optional, but should be included if not obvious.
If args or *kwargs are accepted, # noqa they should be listed as *args and **kwargs.
The format for a parameter is::
name (type): description\n The description may span multiple lines. Following\n lines should be indented. The \"(type)\" is optional.\n\n Multiple paragraphs are supported in parameter\n descriptions.\nParameters:
Name Type Description Defaultparam1 int The first parameter.
requiredparam2 obj:str, optional): The second parameter. Defaults to None. Second line of description should be indented.
None *args Variable length argument list.
() **kwargs Arbitrary keyword arguments.
{} Returns:
Type Descriptionbool True if successful, False otherwise.
The return type is optional and may be specified at the beginning of the Returns section followed by a colon.
The Returns section may span multiple lines and paragraphs. Following lines should be indented to match the first line.
The Returns section supports any reStructuredText formatting, including literal blocks::
{\n 'param1': param1,\n 'param2': param2\n}\nExceptions:
Type DescriptionAttributeError The Raises section is a list of all exceptions that are relevant to the interface.
ValueError If param2 is equal to param1.
super_repo/example_google.py def module_level_function(param1, param2=None, *args, **kwargs):\n \"\"\"This is an example of a module level function.\n\n Function parameters should be documented in the ``Args`` section. The name\n of each parameter is required. The type and description of each parameter\n is optional, but should be included if not obvious.\n\n If *args or **kwargs are accepted, # noqa\n they should be listed as ``*args`` and ``**kwargs``.\n\n The format for a parameter is::\n\n name (type): description\n The description may span multiple lines. Following\n lines should be indented. The \"(type)\" is optional.\n\n Multiple paragraphs are supported in parameter\n descriptions.\n\n Args:\n param1 (int): The first parameter.\n param2 (:obj:`str`, optional): The second parameter. Defaults to None.\n Second line of description should be indented.\n *args: Variable length argument list.\n **kwargs: Arbitrary keyword arguments.\n\n Returns:\n bool: True if successful, False otherwise.\n\n The return type is optional and may be specified at the beginning of\n the ``Returns`` section followed by a colon.\n\n The ``Returns`` section may span multiple lines and paragraphs.\n Following lines should be indented to match the first line.\n\n The ``Returns`` section supports any reStructuredText formatting,\n including literal blocks::\n\n {\n 'param1': param1,\n 'param2': param2\n }\n\n Raises:\n AttributeError: The ``Raises`` section is a list of all exceptions\n that are relevant to the interface.\n ValueError: If `param2` is equal to `param1`.\n\n \"\"\"\n if param1 == param2:\n raise ValueError(\"param1 may not be equal to param2\")\n return True\nWith conda, you can create, export, list, remove, and update environments that have different versions of Python and/or packages installed in them. Switching or moving between environments is called activating the environment. You can also share an environment file and import from \ud83d\udcdd requirements.txt.
\ud83d\udcbb `conda env create -f environment.yaml` Create conda environment <br>\n\ud83d\udcbb `conda activate py310` Activate environment <br>\n\ud83d\udcbb `python --version` Check python version\nDelete existing environment: \ud83d\udcbb conda deactivate \ud83d\udcbb conda remove --name py310 --all
In Python the \ud83d\udcdd requirements.txt file helps manage dependencies. It's a text file that lists the packages that the Python project depends on. All listed packages will be installed in the conda environment.
\ud83d\udcbb pip install -r requirements.txt Install from file
This python package contains a pyproject.toml file that contains build system requirements and information, which are used by pip to build the package. It contains the metadata of the software project.
Astral UV is a modern Python package manager designed for flexibility and speed. Efficient package management is crucial for maintaining consistency and compatibility in Python projects. Tools like pip and virtual environments help manage dependencies, while advanced tools like astral-uv streamline package management workflows further. It focuses on optimizing dependency resolution, improving installation times, and ensuring reproducible builds.
Its key features include:
Install: \ud83d\udcbb pip install uv Install package \ud83d\udcbb uv Check package
Use: \ud83d\udcbb uv python list View available Python versions \ud83d\udcbb uv run Run a command in the project environment
Build and publish: \ud83d\udcbb uv build Build the project into distribution archives \ud83d\udcbb ls dist/ View created distribution \ud83d\udcbb uv publish Build the project into distribution archives
See the official documentation at astral.sh
Used Icons
\ud83d\udc19 GitHub | \ud83d\udca0 git | \ud83d\udcdd File | \ud83d\udcbb Command Line
"}]} \ No newline at end of file diff --git a/develop/user_documentation/code_example/index.html b/develop/user_documentation/code_example/index.html index 6350a65..d4b25e1 100644 --- a/develop/user_documentation/code_example/index.html +++ b/develop/user_documentation/code_example/index.html @@ -155,6 +155,43 @@ + +