Distribution Statement

# # # This source code is subject to the license referenced at

# # # NRLMMD-GEOIPS.

Where to Put Documentation

Flowchart

Please use this flowchart to figure out where to put new documentation.

        flowchart TD
    Start[Start]
    DocBuild{Are you modifying the homepage or how the documentation is built?}
    Templates[Modify files in <em>_templates</em> or <em>_static</em>]
    ReleaseNote[Do you need to add a release note, doing a release or something else?]
    LatestRelease[Add to <em>releases/latest</em>]
    MoveLatest[Move <em>latest</em> to versioned directory and create new empty <em>latest</em>]
    CodeDoc{"Are you documenting code (function, method, file) that doesn't have up-to-date docstrings?"}
    Docstrings[Add docstrings in the relevant code file]
    ContributeInfo{Is it about how to contribute to the project? Or the Scope of the project?}
    ContributeFolder[Add to <em>contribute</em> folder]
    TutorialCheck{Is it a step-by-step tutorial or have explicit steps for someone to complete?}
    TutorialsFolder[Add to <em>tutorials</em> folder]
    ConceptualInfo{Does it deal with how the code works, is laid out or how to use the code?}
    FunctionalityFolder[Add to relevant file in <em>functionality</em>]
    ArchSubfolders{Specific area?}
    ArchDocumentation[Add to <em>architecture/documentation</em>]
    ArchStructure[Add to <em>architecture/structure-of-geoips</em>]
    ArchTests[Add to <em>architecture/tests</em>]
    ArchOther[Look for relevant file in <em>architecture</em>]
    ScopeFolder[Add to <em>concepts/scope</em>]
    FutureCheck{Are you writing about something already implmented and working?}
    FutureFolder[Add to relevant file in <em>concepts/future</em>]
    Consult[Consult with team for appropriate location]

    Start --> DocBuild
    DocBuild -- Yes --> Templates
    Templates
    DocBuild -- No --> ReleaseNote
    ReleaseNote -- Adding Release Note --> LatestRelease
    ReleaseNote -- Release Process --> MoveLatest
    ReleaseNote -- Something else--> FutureCheck

    FutureCheck -- No --> FutureFolder
    FutureCheck -- Yes --> CodeDoc

    CodeDoc -- Yes --> Docstrings
    CodeDoc -- No --> ContributeInfo
    Docstrings -- Need to write more? --> Start

    ContributeInfo -- Contribute --> ContributeFolder
    ContributeInfo -- Scope --> ScopeFolder
    ContributeInfo -- Something else --> TutorialCheck
    TutorialCheck -- Yes --> TutorialsFolder
    TutorialCheck -- No --> ConceptualInfo
    ConceptualInfo -- No / Something else --> Consult
    ConceptualInfo -- How to use code, run tests, or build documentation. --> FunctionalityFolder
    ConceptualInfo -- How/why code works --> ArchSubfolders
    ConceptualInfo -- How code is laid out --> ArchSubfolders

    ArchSubfolders -- Documentation --> ArchDocumentation
    ArchSubfolders -- Tests --> ArchTests
    ArchSubfolders -- Structure of code --> ArchStructure
    ArchSubfolders -- Other --> ArchOther
    

Guidelines

• Modifying Documentation Build: If you’re changing how the documentation is built: - Modify files in the _templates directory. - For Sphinx configuration, edit sphinx_conf.template.py. - The homepage template is also located in _templates.

• Modifying Static Files or Styling: If you’re changing render files or styles: - Modify files in the _static directory.

• Adding Release Notes: - Add new release notes to releases/latest. - During the release process, move latest to a versioned directory and create a new, empty latest directory.

• Documenting Code: - Document functions, methods, or files directly in the code using docstrings, which are integrated into the GeoIPS API. - If more detailed documentation is needed, also write an RST file in the appropriate section.

• Contributing to the Project: - Information about contributing (but not using) goes into the contribute folder.

• Step-by-Step Tutorials: - Add tutorials or any step-by-step instructions to the tutorials folder.

• Conceptual Information: - How the Code Works or Is Organized: Place this information in the concepts directory. - Usage Information: Instructions on how to use or operate something go into concepts/functionality. - Architecture Details: Information on how GeoIPS works internally or why it’s structured a certain way goes into concepts/architecture. Use subfolders for specific topics like documentation or tests. - Scope and Future Plans:

  • Scope: Information about the scope of GeoIPS goes into concepts/scope.

  • Future Plans: Information about future plans goes into concepts/future.

Images/Supporting Files

If documentation requires support files beyond a single .rst file (eg. images), please create a folder and place the support files and the documentation file in side of it. The documentation file should be named index.rst and the folder should be named descriptively. This setup is for clean URLs in built documentation.

Note

If none of the above paths fit your documentation, please consult with the team to find the appropriate location.