Skip to content

Update Documentation Overview and Conventions #2454

@lisagoodrich

Description

@lisagoodrich

Replace italics below with details for this issue.

Update Sphinx online editor

When trying new editing tools, it can be handy to have a quick place to see if the changes actually work or not in Sphinx. Without this editor it can take up to 5 minutes to see if the changes worked while it builds in ReadTheDocs. Having an online editor makes things run more smoothly.

The OLD editor was livesphinx and is no longer working or supported. (There was another version before this one that is also out of service.)

The NEW editor is https://www.tutorialspoint.com/online_restructure_editor.php and needs to be updated in section 10.2.19.1. Testing RST Formatting in an Online Editor.

Update tables information

  1. It is possible to use csv files to automatically create tables. Add something like this information to our tables section.

  2. Also note this example of a grid table under 3.4.3. External Library Handling in compile_MET_all.sh of the MET installation guide, IF THE USER ALREADY HAS THE LIBRARY DEPENDENCIES INSTALLED table. John HG had to do some fancy maneuvering to get this to line up correctly. Please note that that one way to force table to use line break inside a cell is inserting an empty line between them. This works in a gridded table. Please note, this is currently in a feature branch, not develop: https://met.readthedocs.io/en/feature_2588_install_rewrite/Users_Guide/installation.html#external-library-handling-in-compile-met-all-sh

  3. If it's a list table, to create a line break use :raw-html:<br /> see Table 13.8 Format information for SSVAR line 37-38 as an example. Here is the raw sphinx.

Update code within a paragraph

Add this information to the code blocks section

To add coding information within a paragraph:
:code:information to highlight

Adding a section for Duplicate Links

This will address the "WARNING: Duplicate explicit target name". Add this under Troubleshooting.

Time Estimate

Estimate the amount of work required here.
1 to 3 days

Sub-Issues

Consider breaking the task down into sub-issues.

  • Add a checkbox for each sub-issue here.

Relevant Deadlines

List relevant project deadlines here or state NONE.

Funding Source

2702691, 2784543 and 2799991 equally

Define the Metadata

Assignee

  • Select engineer(s) or no engineer required
  • Select scientist(s) or no scientist required

Labels

  • Select component(s)
  • Select priority
  • Select requestor(s)

Projects and Milestone

  • Select Repository and/or Organization level Project(s) or add alert: NEED CYCLE ASSIGNMENT label
  • Select Milestone as the next official version or Future Versions

Define Related Issue(s)

Consider the impact to the other METplus components. This is not a change that will effect other modules

Task Checklist

See the METplus Workflow for details.

  • Complete the issue definition above, including the Time Estimate and Funding Source.
  • Fork this repository or create a branch of develop.
    Branch name: feature_<Issue Number>_<Description>
  • Complete the development and test your changes.
  • Add/update log messages for easier debugging.
  • Add/update unit tests.
  • Add/update documentation.
  • Add any new Python packages to the METplus Components Python Requirements table.
  • Push local changes to GitHub.
  • Submit a pull request to merge into develop.
    Pull request: feature <Issue Number> <Description>
  • Define the pull request metadata, as permissions allow.
    Select: Reviewer(s) and Development issues
    Select: Repository level development cycle Project for the next official release
    Select: Milestone as the next official version
  • Iterate until the reviewer(s) accept and merge your changes.
  • Delete your fork or branch.
  • Close this issue.

Metadata

Metadata

Assignees

Type

No type

Projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions