MetOffice / MetOffice/lfric_core

[Documentation]: Standardise restructured text

Open
#156 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Fortran
Stars
26
Forks
73
Avg merge
1d 8h
Merged PRs (30d)
4

Description

### Contact Details

_No response_

### Are there any linked Issues or Pull Requests?

_No response_

### Brief description

Use a linter (e.g., `doc8`, `rstcheck`, etc) to check integrity of restructured text. Ignoring the line lengths issues, there are ~40 errors reported by `doc8`.

```
./documentation/source/index.rst:103: D002 Trailing whitespace
./documentation/source/index.rst:117: D002 Trailing whitespace
./documentation/source/index.rst:122: D002 Trailing whitespace
./documentation/source/index.rst:130: D002 Trailing whitespace
./documentation/source/index.rst:131: D002 Trailing whitespace
./documentation/source/index.rst:132: D002 Trailing whitespace
./documentation/source/index.rst:136: D002 Trailing whitespace
./documentation/source/index.rst:144: D002 Trailing whitespace
./documentation/source/index.rst:145: D002 Trailing whitespace
./documentation/source/index.rst:150: D002 Trailing whitespace
./documentation/source/index.rst:158: D002 Trailing whitespace
./documentation/source/index.rst:159: D002 Trailing whitespace
./documentation/source/getting_started/index.rst:19: D002 Trailing whitespace
./documentation/source/getting_started/index.rst:20: D002 Trailing whitespace
./documentation/source/how_it_works/parallelism/lfric_mpi.rst:18: D002 Trailing whitespace
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:45: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:46: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:54: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:58: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:59: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:60: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:62: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:63: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:123: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:124: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:125: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:222: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:223: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:224: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:261: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:262: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:297: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_configuration_namelists.rst:298: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_generators.rst:62: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_generators.rst:64: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_generators.rst:65: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_generators.rst:66: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_generators.rst:68: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/meshes/mesh_generators.rst:69: D003 Tabulation used for indentation
./documentation/source/how_to_use_it/parallelism/lfric_message_passing_interface.rst:26: D002 Trailing whitespace
./documentation/source/how_to_contribute/coding_standards/fortran_coding_standards.rst:315: D000 Bullet list ends without a blank line; unexpected unindent.
./documentation/source/how_to_contribute/coding_standards/fortran_coding_standards.rst:353: D002 Trailing whitespace
./documentation/source/how_to_contribute/coding_standards/fortran_coding_standards.rst:355: D002 Trailing whitespace
```

### Further details of the issue.

_No response_

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running doc8 against the files under documentation/source listed in the issue, while ignoring line-length findings. Fix the reported trailing whitespace, tab indentation, and bullet-list formatting without changing the documentation content. Done means the listed D002, D003, and D000 errors no longer appear.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.