Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Write Agent documentation best practices #221

Merged
merged 19 commits into from
Sep 10, 2021
Merged

Write Agent documentation best practices #221

merged 19 commits into from
Sep 10, 2021

Conversation

BrianJKoopman
Copy link
Member

Description

There was a long discussion in #13 about documenting the best practices for writing Agent Task/Process documentation. This attempts to capture the result of that discussion and document the requirements for writing Task/Process docs.

In addition to the example added to the Agents page of the developers guide (which itself needs some attention soon) I've applied these practices to the Aggregator Agent. Part of this started resolving issues in #138, so I've tried to address everything there too.

Motivation and Context

Fixes #13

How Has This Been Tested?

Not yet tested, should be read by someone else.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

  • My code follows the code style of this project.
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • Unless I am preparing a release, I have opened this PR onto the develop branch.

@BrianJKoopman
Copy link
Member Author

BrianJKoopman commented Aug 26, 2021 •
edited
Loading

I've opened this as a draft for the moment. I've written up the best practices we discussed the other day. I tried applying them to the Aggregator Agent, and have tried organizing the Agent Reference page for the Aggregator a bit. One thing we didn't touch on really was the structure of these pages, but I'd also like to standardize these a bit, especially when it comes to things like the config examples and Agent API sections. I think presenting agent information in a consist way will be helpful for users trying to quickly find reference material.

Thoughts on the structure I've applied to the Aggregator Agent page?

My hope is to get a bit of feedback on this before updating the other core Agents' pages.

socs Agent pages I used a bit for reference:

@BrianJKoopman
Write task/process documentation guidelines
e1e43b8
@BrianJKoopman
Restructure Aggregator Agent docs page
3654173 
I also rewrote some small segments and added links to resolve some points
from #138.

fixes #138
@BrianJKoopman
Resolve sphinx build warning
8651a11 
aggregator.py:docstring of ocs.agent.aggregator.g3_cast:5:
WARNING: Definition list ends without a blank line; unexpected unindent.
@BrianJKoopman
Update Aggregator Agent's task/process docstrings
2041c5c 
This follows the new guidelines for best practices in documenting
tasks/processes. This renames start_aggregate to record to match the registered
task name in ocs. Mark the stop process (also renamed) and other methods as
private where appropriate.
@BrianJKoopman
Write guidelines for Agent Reference pages
bc72a4f
@BrianJKoopman
Create agent docs page template
60d6526
@BrianJKoopman
Move config file examples higher on aggregator agent page
7717cba
@BrianJKoopman
Standardize the InfluxDB Agent docs
1e041b5
@BrianJKoopman
Standardize Registry Agent docs
2de1b9f
@BrianJKoopman
Standardize FakeDataAgent docs
61974ec
@BrianJKoopman
Standardize HostMaster Agent docs
f526cdd
@BrianJKoopman
Make headings and docker images consistent
9f52528 
Headings under "Configure File Examples" were inconsistent across Agents, and
not all Agents had :latest listed as a Docker tag.
@BrianJKoopman
Mark optional params as such
05b0fdb
@BrianJKoopman
Fix only remaining Sphinx build warning
8379e5b
@BrianJKoopman
Make some small wording adjustments in agent doc guide
2062087
@BrianJKoopman BrianJKoopman force-pushed the agent-docs-best-practices branch from 21b1bb3 to 2062087 Compare September 7, 2021 18:29
@BrianJKoopman BrianJKoopman marked this pull request as ready for review September 7, 2021 20:06
@BrianJKoopman BrianJKoopman added the documentation Requires documentation label Sep 7, 2021
mhasself
mhasself approved these changes Sep 9, 2021
View reviewed changes
Copy link
Member

@mhasself mhasself left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great. Minor stuff inline.

agents/fake_data/fake_data_agent.py Outdated Show resolved Hide resolved
agents/host_master/host_master.py Outdated Show resolved Hide resolved
agents/host_master/host_master.py Outdated Show resolved Hide resolved
agents/host_master/host_master.py Outdated Show resolved Hide resolved
docs/agents/aggregator.rst Outdated Show resolved Hide resolved
docs/developer/agents.rst Outdated Show resolved Hide resolved
@BrianJKoopman BrianJKoopman linked an issue Sep 10, 2021 that may be closed by this pull request
Aggregator docs need an upgrade #138
Closed
@BrianJKoopman BrianJKoopman merged commit 2d1f1c6 into develop Sep 10, 2021
@BrianJKoopman BrianJKoopman deleted the agent-docs-best-practices branch September 10, 2021 20:29
@BrianJKoopman BrianJKoopman mentioned this pull request Nov 29, 2021
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@mhasself mhasself mhasself approved these changes

@jlashner jlashner Awaiting requested review from jlashner

Assignees
No one assigned
Labels
documentation Requires documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Aggregator docs need an upgrade Document the best practices for Agent comments
2 participants
@BrianJKoopman @mhasself