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.

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

Generate documentation for parameter and return fields with tables #162

Open
RyanGlScott opened this issue Apr 7, 2021 · 0 comments
Open
Labels
Docs Documentation Feature A new thing that would be good

Comments

@RyanGlScott
Copy link
Contributor

Currently, argo's autogenerated documentation for each server method includes the method's parameters and results in subsections. They look like this:

argo

This is OK, but in my opinion, there is room for improvement. The sections for the load and clear commands are intended to have a larger font size than their Parameter fields and Return fields subsections, but the difference in size in pretty subtle. To make this more obvious, I think it would be better to format this information with RST tables, like what SAW's handwritten remote API documentation currently does. Here is what the that looks like:

argo2

With tables, it's very obvious where one method stops and another begins, and it looks nicer overall. Currently, argo doesn't support autogenerating the markdown for RST tables, but I don't imagine that it would be terribly difficult to teach argo how to do this. Here is what the markdown for the tables above look like, for reference:

Cryptol Module Management
=========================

Loading Modules
---------------

:Method name:
  ``SAW/Cryptol/load module``
:Parameters:
  - ``module name``: The name of the Cryptol module to be loaded.

Loading Files
-------------

:Method name:
  ``SAW/Cryptol/load file``
:Parameters:
  - ``file``: The name of the Cryptol source file to be loaded.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Docs Documentation Feature A new thing that would be good
Projects
None yet
Development

No branches or pull requests

1 participant