# Copilot general instructions

## Docstring Formatting

All docstrings for python functions, classes, methods and modules should confirm to the following:

- Generally the format is based on Google stadnard
- Written in British English
- There is a one line suymmary that starts on the same line as the opening quotes and terminated with a period.
- All public classes, methods and functions should conform to the following:

  - The position areguments are described in an Args: section, the keyword parameters in a
    "Keyword Parameters:" section.
  - Parameters are listed as "name (type):" then a newline and indent with the descritpion.
  - Return values are in a "Returns:" section. For single return values the format is "(type):" newline and
    indent and then description. Tuples (multiple return values) are given a sequyence of single value
    blocks.
  - Exceptions that are specifically raised are in a "Raises:" section.
  - Class atributes are in a "Attributes:" section and follow a similar structure to parameters.
  - Any details of the algorithm etc are in a "Notes:" section.
  - Public methods and functions should have examples of usage in an "Examples:" section
  - The Class constructor should be documented in the class docstring rather than the __init__ method's docstring.

- Private mthods, functions should conform to the following:

  - If the function or method is called outside of the same scope (e.g. in an inherited class or different
    module) then it should be documented as a publuc method or function
  - Otherwise, only the summary needs to be probided and other sections are optional.

- Modules should conform to the following:

  - The docstring should include a brief overview of the contents of the module, higlighting common aspects
    of te contents.

## Code formatting

### Class, function, method and variable naming conventions

The following apply to entities created by copilot. Unless specifically instructed, do not rename
existing entities that do not conform to the following.

- Classes should follow PascalCase conventions
- functions, methods and variables not in module level scope follow snake_case conventions
- Variables in the module level scope follow CAPITAL case convention

### imports

Group ipmorts as follows:

- standard library imports
- well known third party packages such as numpy, matplotlib, scipy, pandas
- other third party packages
- imports from within this package, including relative imports

Within each group, sort imports alphabetically. Where possible combine imports from the same module into one statement.

### Line length

- For user examples, the line length is 79 characters, for all other files use 119 characters.
- Otherwise folow black coding standards.
- Avoid line splits that are not compatible with the versions of python
  specified in the package building scripts.
- remove trailing whitespace at the end of lines
- Ensure blank lines only contain an end of line character and not any other whitespace.

## Issues and Bugs discovered during copilot operations

If a new issue or bug is discovered during editing or creating other features, create a GitHub issue to track it.
When creating issues, include:

- A clear, descriptive title
- The file path and line number where the issue occurs
- A detailed description of the issue
- Steps to reproduce (if applicable)
- Suggested fixes or approaches (if known)
- Appropriate labels (bug, enhancement, documentation, etc.)

If a GitHub issue is fixed during your work, close the issue with a reference to the commit or PR that fixed it.

## Markdown Formatting

When changing markdown files, follow these guidelines:

- Use markdownlint to identify errors in markdown formatting and fix any it flags.
- Use a maximum line length of 119 characters.
- Use British English spellings in text except where code requires differently.
- Pay particular attention to spacing around lists, headers and code blocks.
- Verify that files referenced in mardown files, such as images, actually exist.

## Examples and Figures Directory

The `examples/figures/` directory contains example output figures that are used in the documentation and README.md.

- __DO NOT__ add `examples/figures/` to `.gitignore` - these files must be committed to the repository.
- The figures in this directory are essential for documentation and are referenced by:
  - README.md (e.g., fig05a.png in the repository header)
  - Documentation files in docs/source/ (multiple RST files reference these figures)
- The figures can be regenerated by running the test suite: `pytest tests/stonerplots/test_examples.py`
- If figures are accidentally removed or deleted, restore them from git history rather than regenerating,
  as the generated figures should match the committed versions for consistency.
