MidasTechnologiesInc/MidasEngine
3
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Entirely new file path. Addd Standard Practices, Moved Docs

Browse Source
This commit is contained in:
klein panic
2024-11-01 01:20:14 -04:00
parent b00fc25044
commit c98fffeada
38 changed files with 2201 additions and 455 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
docs/PoliciesAndStandards/DocumentationStandards.md Normal file
View File

@@ -0,0 +1,170 @@
# Documentation Standards
## Table of Contents
1. [Overview](#overview)
2. [Global Documentation Structure](#global-documentation-structure)
3. [Module-Specific Documentation](#module-specific-documentation)
4. [Documentation Format and Naming Conventions](#documentation-format-and-naming-conventions)
5. [File Requirements for Python Modules](#file-requirements-for-python-modules)
6. [Code Documentation Practices](#code-documentation-practices)
---
## Overview
This document defines the standards for documenting business, technical, and code-related affairs within the repository. It ensures that all contributors understand how and where to document essential aspects of the project, including code structure, usage, and business elements.
**Footnote:** While the overarching program is under active development, documentation must be updated with each pull request or addition to maintain consistency and clarity as the project grows.
---
## Global Documentation Structure
All global documentation is stored under the `/docs` directory and is organized into the following key areas:
1. **Business Documentation**:
- Contains non-technical documents that relate to company operations, legal compliance, project plans, business strategies, and any necessary licenses or contracts.
- **Directory**: `/docs/business`
- **Examples**: Business plans, contracts, project outlines, licenses.
2. **Policies and Standards**:
- Contains files outlining the coding, review, and workflow standards.
- **Directory**: `/docs/policies-and-standards`
- **Examples**: `GitAndGitHubStandards.md`, `BranchNamingConventions.md`, `CodingStandards.md`.
3. **Man Pages**:
- Stores all program-related documentation for the entire codebase.
- **Directory**: `/docs/manpages`
- **Examples**: README files detailing how to use, deploy, and modify the overarching program.
Each sub-directory should contain a README.md that outlines its purpose and lists the contents within.
---
## Module-Specific Documentation
All **root modules** within the overarching program should contain their own `README.md` files. These files should act as module-specific documentation, providing:
1. **Overview**:
- A brief explanation of the module’s functionality and its purpose in the larger program.
2. **Installation and Setup**:
- Instructions for setting up the module, including any dependencies not covered in the global requirements file.
3. **Usage**:
- How to run and utilize the module, including examples of inputs, expected outputs, and special configurations.
4. **Development Guidelines**:
- If applicable, detail any specific guidelines for contributing to the module, such as coding standards, testing guidelines, or branch usage specific to the module.
5. **Version and Dependencies**:
- Each module should have its own `requirements.txt` file that lists the dependencies required for it to function. This file will be merged into the main program’s `requirements.txt` by the admins.
---
## Documentation Format and Naming Conventions
### Format
- **Markdown** (`.md`) or **Plain Text** (`.txt`) formats are acceptable for all documentation.
- The language should be formal yet accessible, avoiding technical jargon where possible to ensure clarity for all team members and future collaborators.
### Naming Conventions
- **Documentation files** must be in **Capitalized Case** with no spaces, using only letters and alphanumeric characters.
- **Examples**: `DocumentationStandards.md`, `GitAndGitHubStandards.md`
- **Code files** should follow **lowercase with underscores** for Python, with no spaces or special characters.
- **Examples**: `data_processing.py`, `config_handler.py`
---
## File Requirements for Python Modules
### Main `requirements.txt`
A main `requirements.txt` file will exist in the root directory of the program. This file aggregates all module-specific dependencies to provide a comprehensive list of requirements for the entire program.
### Module-Specific `requirements.txt`
- Each root module in Python must include its own `requirements.txt` file, specifying only the dependencies necessary for that module.
- Upon review, the admins will incorporate module-specific requirements into the main `requirements.txt`.
---
## Code Documentation Practices
### General Code Documentation Guidelines
Documentation within code should provide clarity and context without redundancy. Focus on documenting the **why** and **how** rather than the **what**.
- **Functions and Methods**:
- Include docstrings for all public functions and methods. These should follow the [Google Docstring Style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for consistency and readability.
- **Classes**:
- Each class should have a docstring explaining its purpose and any unique attributes or methods. This docstring should summarize the role of the class in the module.
### Specific Documentation Guidelines
1. **Function-Level Documentation**:
- Include a brief docstring at the beginning of each function that explains:
- **Parameters**: List and explain the function’s input parameters.
- **Returns**: Describe the data returned by the function.
- **Raises**: Detail any exceptions that the function might raise.
- **Example**:
```python
def process_data(data: list) -> dict:
"""
Processes input data and returns a dictionary of results.
Args:
data (list): List of data points to be processed.
Returns:
dict: Processed results including mean and standard deviation.
Raises:
ValueError: If data is not a list of numbers.
"""
```
2. **Class-Level Documentation**:
- Use class-level docstrings to summarize the purpose and usage of the class.
- **Example**:
```python
class DataProcessor:
"""
Class for processing and analyzing data.
This class provides methods for statistical analysis and
data transformation. Suitable for numerical data inputs.
Attributes:
data (list): List of numerical data.
"""
```
3. **In-Line Comments**:
- Use in-line comments sparingly and only to clarify complex logic or non-standard decisions in the code.
- Avoid obvious comments; instead, focus on why something is done rather than what is being done.
### API Documentation Standards
For code that interfaces with external services or shared modules, follow these standards for documenting APIs:
- **Endpoints**: Clearly list each endpoint and its purpose in the API documentation.
- **Parameters**: Define all required and optional parameters, including data types and default values.
- **Response Format**: Describe the structure and data types returned by each endpoint.
- **Error Handling**: Document possible error codes or messages and recommended solutions for common issues.
- **Usage Examples**: Provide examples showing both requests and responses to illustrate expected usage.
API documentation should be added to the `docs/ManPages/api` directory. Where possible, maintain consistency with other project documentation.
### Documentation Updates with Pull Requests
Whenever a pull request (PR) introduces new features, refactors existing code, or modifies functionality, relevant documentation files must be updated accordingly. Contributors are responsible for ensuring that:
- All impacted `README.md` files, both module-specific and global, reflect the latest changes.
- Necessary updates to docstrings, function comments, and inline comments are made to maintain clarity and usability.
*Footnote: This process is currently noted for future enforcement once the overarching program is complete.*