0

What is the standard sphinx docstring format for module command line parameters? For example:

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('-f', '--file', default=f'{PATH}/data/', help='excel spreadsheet')
    args = parser.parse_args()
    main(args.file)

I'd rather document this manually than use the sphinx argparse extension. I've considered using the method below for the module docstring but I don't now if it is the standard method, nor how to indicate the -f flag. Additionally, I'm actually using numpy-style docstrings but I'm leaving the standard sphinx formats here so more people can understand it.

:param file: excel spreadsheet
:ptype file: str
Hersh Joshi
  • 419
  • 3
  • 13
  • Assuming your use of argparse is for a script the prevalent form of documenting it is using a [synopsis](https://stackoverflow.com/questions/19885821/how-do-i-use-installed-packages-in-pycharm) and [options](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#options) listing. If you notice carefully there aren't any docstrings involved because what you're documenting is an executable. So any docstrings are usually meant to remain in the source code and don't usually make the final user documentation. – bad_coder Feb 19 '22 at 03:20
  • What you really want to show in the documentation are those `help=` fileds under the flags, the problem is they aren't docstrings and if you write them in a docstring you just duplicated the code you have to maintain, so you defeated the purpose of automation and might as well maintain the duplicated code in the `.rst` file itself since the autodoc directive wouldn't give you the usual command-line formatting anyway (and that's why using an extension for argparse is so convenient...) – bad_coder Feb 19 '22 at 03:32
  • Sorry, here's the link to the [synopsis](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#synopsis) I pasted the wrong link in my first comment. – bad_coder Feb 19 '22 at 13:08
  • 1
    @bad_coder thanks for the help. You've convinced me that using a separate .rst file along with sphinx-argparse makes the most sense so I'll go with that. – Hersh Joshi Feb 21 '22 at 15:30

0 Answers0