Skip to content

README.md

Latest commit

 

History

History
270 lines (190 loc) · 7.93 KB

README.md

File metadata and controls

270 lines (190 loc) · 7.93 KB

RegressionLab Documentation

This directory contains the complete documentation for RegressionLab. The documentation is organized to serve both end users and developers.

Documentation Structure

User Documentation

Getting Started

  • index.md - Main documentation index and overview
  • introduction.md - Project introduction, objectives, and benefits
  • installation.md - Installation instructions for all platforms
  • usage.md - General user guide covering all operation modes

Configuration & Customization

Developer Documentation

  • extending.md - How to add new fitting functions
  • customization.md - How to replace the fitting core (SciPy alternatives)
  • api/ - Technical API documentation for developers

Reference & Support

Quick Navigation

I want to...

...get started quickly → Start with Introduction, then Installation

...learn how to use RegressionLab → Read the User Guide, then interface-specific guides:

...customize the appearance → See Configuration Guide

...add a new equation → Follow Extending RegressionLab

...use a different optimization library → Read Customizing the Fitting Core

...contribute to the project → Check Contributing Guidelines

...fix a problem → Search Troubleshooting Guide

...understand the code → Browse API Documentation

For ReadTheDocs / Sphinx

This documentation is designed to be compatible with ReadTheDocs and Sphinx. To build the documentation with Sphinx:

Setup

cd sphinx-docs
pip install -r requirements.txt

Build

Linux/macOS:

./build_docs.sh

Windows:

build_docs.bat

View

Linux/macOS:

./open_docs.sh

Windows:

open_docs.bat

The built documentation will be in sphinx-docs/build/html/.

Markdown Features Used

This documentation uses standard Markdown with these extensions:

  • Code blocks with syntax highlighting
  • Tables for structured data
  • Links (internal and external)
  • Images (stored in images/ subdirectory)
  • Admonitions (Note, Warning, etc. - for Sphinx)
  • Math (LaTeX syntax - for Sphinx)

Documentation Standards

When contributing to documentation:

Style Guide

  1. Be clear and concise: Use simple language.
  2. Use examples: Code examples, screenshots, workflows.
  3. Link related content: Cross-reference other documentation.
  4. Stay up-to-date: Update docs when code changes.
  5. Test examples: Ensure code examples actually work.

File Naming

  • Use lowercase with hyphens: configuration-guide.md.
  • Be descriptive: installation.md not install.md.
  • Group related files: api/ directory for API docs.

Structure

Each document should have:

  1. Title (H1): Clear, descriptive.
  2. Introduction: What this document covers.
  3. Table of contents (for long docs).
  4. Sections (H2, H3): Logical organization.
  5. Examples: Where appropriate.
  6. Cross-references: Links to related docs.
  7. Navigation: "Next steps" or "See also".

Code Examples

# Always include:
# 1. Comments explaining what the code does
# 2. Expected output or behavior
# 3. Complete, runnable examples when possible

import numpy as np
from fitting.fitting_functions import func_lineal

# Example: Calculate y values for linear function
x = np.array([1, 2, 3, 4, 5])
m = 2.5
y = func_lineal(x, m)

print(y)  # Output: [ 2.5  5.   7.5 10.  12.5]

Screenshots

  • Store in docs/images/.
  • Use descriptive filenames: tkinter-main-menu-spanish.png.
  • Include in both languages if UI differs.
  • Optimize file size (< 500 KB per image).
  • Use PNG for UI screenshots, JPEG for photos.

Building Locally

Preview Markdown

Use a Markdown previewer:

  • VS Code: Built-in Markdown preview (Ctrl+Shift+V)
  • Typora: WYSIWYG Markdown editor
  • Grip: GitHub-flavored Markdown preview 
    pip install grip
grip docs/index.md

Build Sphinx Documentation

From project root:

cd sphinx-docs
make html          # Linux/macOS
.\make.bat html    # Windows

View at: sphinx-docs/build/html/index.html

Documentation Checklist

When adding or updating documentation:

  • Content is accurate and up-to-date
  • Examples are tested and work
  • Screenshots are current (if applicable)
  • Links work (internal and external)
  • Spelling and grammar checked
  • Code blocks have syntax highlighting
  • Cross-references added where helpful
  • Updated table of contents (if applicable)
  • Follows style guide
  • Builds successfully with Sphinx (no warnings)

Localization

Documentation supports English and Spanish via Sphinx i18n (gettext). ReadTheDocs hosts both:

  • English: https://regressionlab.readthedocs.io/en/latest/
  • Spanish: https://regressionlab-es.readthedocs.io/es/latest/ (separate project linked as translation)

ReadTheDocs setup (Spanish project)

  1. On ReadTheDocs, create a new project (e.g. regressionlab-es).
  2. Import the same Git repository as the English project.
  3. In Admin → Settings → Language, select Spanish.
  4. In the parent project (regressionlab), go to Admin → Translations and add regressionlab-es as a translation.
  5. Both projects share .readthedocs.yaml; ReadTheDocs sets READTHEDOCS_LANGUAGE per project.

Translating content

  1. Regenerate .pot files: python -m sphinx -b gettext sphinx-docs/source sphinx-docs/build/gettext
  2. Update Spanish .po files: sphinx-intl update -p sphinx-docs/build/gettext -l es -d sphinx-docs/locale
  3. Edit sphinx-docs/locale/es/LC_MESSAGES/*.po (fill msgstr with translations).
  4. Compile .po to .mo (required for Sphinx to use translations): sphinx-intl build -d sphinx-docs/locale
  5. Rebuild HTML with Spanish: make -C sphinx-docs html-es (or sphinx-build -b html -D language=es sphinx-docs/source sphinx-docs/build/html-es).
  6. Commit and push; ReadTheDocs will run step 4 automatically before building.

Feedback

Documentation feedback is welcome!

  • Typos/errors: Open a pull request with fixes.
  • Missing content: Open an issue describing what's needed.
  • Unclear sections: Open an issue with suggestions.
  • Questions: Use GitHub Discussions.

Maintenance

Documentation should be reviewed and updated:

  • With each release: Update version numbers, screenshots.
  • When code changes: Update affected sections.
  • Quarterly: Review for accuracy and completeness.
  • When issues reported: Fix problems promptly.

Resources

Markdown

Sphinx

Writing

Documentation Version: 1.1.2
Last Updated: February 2026
Maintainer: Alejandro Mata Ali