Sphinx and argparse - autodocumenting command line scripts?












25















I'm building a Python package, and using Sphinx to create the docs. Aside from my package code, I also include a lot of command line Python scripts, which use argparse. I was wondering if there is a way to get Sphinx to autodocument these scripts? The end goal would be a pretty-printed list of scripts, with the associated help print, arguments and options. And to be clear, I'm looking for a pre-existing way to do this, not a way to implement this myself.



This isn't as specific of a question as I usually ask on S.O., if there is a more appropriate S.E. site to post this question, please let me know. Thanks.






python documentation python-sphinx argparse







share|improve this question

























  • Unrelated, but might be helpful. Check plac package on PyPI.

    – Mikko Ohtamaa
    Jun 4 '12 at 21:58











  • Don't think it helps me with this, but interesting, thanks for the heads-up.

    – jeremiahbuddha
    Jun 4 '12 at 22:55
















25















I'm building a Python package, and using Sphinx to create the docs. Aside from my package code, I also include a lot of command line Python scripts, which use argparse. I was wondering if there is a way to get Sphinx to autodocument these scripts? The end goal would be a pretty-printed list of scripts, with the associated help print, arguments and options. And to be clear, I'm looking for a pre-existing way to do this, not a way to implement this myself.



This isn't as specific of a question as I usually ask on S.O., if there is a more appropriate S.E. site to post this question, please let me know. Thanks.






python documentation python-sphinx argparse







share|improve this question

























  • Unrelated, but might be helpful. Check plac package on PyPI.

    – Mikko Ohtamaa
    Jun 4 '12 at 21:58











  • Don't think it helps me with this, but interesting, thanks for the heads-up.

    – jeremiahbuddha
    Jun 4 '12 at 22:55














25












25








25


4






I'm building a Python package, and using Sphinx to create the docs. Aside from my package code, I also include a lot of command line Python scripts, which use argparse. I was wondering if there is a way to get Sphinx to autodocument these scripts? The end goal would be a pretty-printed list of scripts, with the associated help print, arguments and options. And to be clear, I'm looking for a pre-existing way to do this, not a way to implement this myself.



This isn't as specific of a question as I usually ask on S.O., if there is a more appropriate S.E. site to post this question, please let me know. Thanks.






python documentation python-sphinx argparse







share|improve this question
















I'm building a Python package, and using Sphinx to create the docs. Aside from my package code, I also include a lot of command line Python scripts, which use argparse. I was wondering if there is a way to get Sphinx to autodocument these scripts? The end goal would be a pretty-printed list of scripts, with the associated help print, arguments and options. And to be clear, I'm looking for a pre-existing way to do this, not a way to implement this myself.



This isn't as specific of a question as I usually ask on S.O., if there is a more appropriate S.E. site to post this question, please let me know. Thanks.






python documentation python-sphinx argparse




python documentation python-sphinx argparse






share|improve this question















share|improve this question













share|improve this question




share|improve this question








edited Jun 6 '12 at 11:56









bmu

22.1k87693




22.1k87693










asked Jun 4 '12 at 19:08









jeremiahbuddhajeremiahbuddha

5,29921830




5,29921830













  • Unrelated, but might be helpful. Check plac package on PyPI.

    – Mikko Ohtamaa
    Jun 4 '12 at 21:58











  • Don't think it helps me with this, but interesting, thanks for the heads-up.

    – jeremiahbuddha
    Jun 4 '12 at 22:55



















  • Unrelated, but might be helpful. Check plac package on PyPI.

    – Mikko Ohtamaa
    Jun 4 '12 at 21:58











  • Don't think it helps me with this, but interesting, thanks for the heads-up.

    – jeremiahbuddha
    Jun 4 '12 at 22:55

















Unrelated, but might be helpful. Check plac package on PyPI.

– Mikko Ohtamaa
Jun 4 '12 at 21:58





Unrelated, but might be helpful. Check plac package on PyPI.

– Mikko Ohtamaa
Jun 4 '12 at 21:58













Don't think it helps me with this, but interesting, thanks for the heads-up.

– jeremiahbuddha
Jun 4 '12 at 22:55





Don't think it helps me with this, but interesting, thanks for the heads-up.

– jeremiahbuddha
Jun 4 '12 at 22:55












3 Answers
3






active

oldest

votes


















17














You can use sphinxcontrib.programoutput to include the help messages from the command line in your documentation.



This is not specific to argparse but can be used to document any script printing help messages to the command line.






share|improve this answer

































    19














    Use sphinx-argparse extension:



    http://sphinx-argparse.readthedocs.org/en/latest/






    share|improve this answer



















    • 1





      Excellent. Is there a way to have the "usage" block treated differently? For me, having it as a literal block isn't quite right.

      – orome
      Jan 21 '14 at 21:43






    • 1





      And while I'm at it, it would be nice of the output for options matched what .. option:: produces: flags only (no default indicated), aligned all the way to the left with less indentation for the description, and changing the first letter to caps and adding a period at the end if one is not already there (since the idiom for --help is to omit these and use all lowercase). Also perhaps flag entries that match the help help output more closely (e.g. -cols [COL [COL ...]] rather than just cols), since all the text is written in that context.

      – orome
      Jan 21 '14 at 22:26











    • Seems to have an error: pastebin.com/jXAz1qHw

      – Martin Thoma
      Oct 20 '14 at 15:34



















    4














    You can use sphinxcontrib.autoprogram. pip install sphinxcontrib-autoprogram, then put 



    extensions += ['sphinxcontrib.autoprogram']


    in your conf.py. To document command cli.py by importing cli with the argparse parser object parser (which can be a Python expression, like a function get_parser()), use



    .. autoprogram:: cli:parser
    
   :prog: cli.py





    share|improve this answer























      Your Answer






      StackExchange.ifUsing("editor", function () {
      StackExchange.using("externalEditor", function () {
      StackExchange.using("snippets", function () {
      StackExchange.snippets.init();
      });
      });
      }, "code-snippets");

      StackExchange.ready(function() {
      var channelOptions = {
      tags: "".split(" "),
      id: "1"
      };
      initTagRenderer("".split(" "), "".split(" "), channelOptions);

      StackExchange.using("externalEditor", function() {
      // Have to fire editor after snippets, if snippets enabled
      if (StackExchange.settings.snippets.snippetsEnabled) {
      StackExchange.using("snippets", function() {
      createEditor();
      });
      }
      else {
      createEditor();
      }
      });

      function createEditor() {
      StackExchange.prepareEditor({
      heartbeatType: 'answer',
      autoActivateHeartbeat: false,
      convertImagesToLinks: true,
      noModals: true,
      showLowRepImageUploadWarning: true,
      reputationToPostImages: 10,
      bindNavPrevention: true,
      postfix: "",
      imageUploader: {
      brandingHtml: "Powered by u003ca class="icon-imgur-white" href="https://imgur.com/"u003eu003c/au003e",
      contentPolicyHtml: "User contributions licensed under u003ca href="https://creativecommons.org/licenses/by-sa/3.0/"u003ecc by-sa 3.0 with attribution requiredu003c/au003e u003ca href="https://stackoverflow.com/legal/content-policy"u003e(content policy)u003c/au003e",
      allowUrls: true
      },
      onDemand: true,
      discardSelector: ".discard-answer"
      ,immediatelyShowMarkdownHelp:true
      });


      }
      });














      draft saved

      draft discarded


















      StackExchange.ready(
      function () {
      StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f10886841%2fsphinx-and-argparse-autodocumenting-command-line-scripts%23new-answer', 'question_page');
      }
      );

      Post as a guest















      Required, but never shown

























      3 Answers
      3






      active

      oldest

      votes








      3 Answers
      3






      active

      oldest

      votes









      active

      oldest

      votes






      active

      oldest

      votes









      17














      You can use sphinxcontrib.programoutput to include the help messages from the command line in your documentation.



      This is not specific to argparse but can be used to document any script printing help messages to the command line.






      share|improve this answer






























        17














        You can use sphinxcontrib.programoutput to include the help messages from the command line in your documentation.



        This is not specific to argparse but can be used to document any script printing help messages to the command line.






        share|improve this answer




























          17












          17








          17







          You can use sphinxcontrib.programoutput to include the help messages from the command line in your documentation.



          This is not specific to argparse but can be used to document any script printing help messages to the command line.






          share|improve this answer















          You can use sphinxcontrib.programoutput to include the help messages from the command line in your documentation.



          This is not specific to argparse but can be used to document any script printing help messages to the command line.







          share|improve this answer














          share|improve this answer



          share|improve this answer








          edited Jun 6 '12 at 11:55

























          answered Jun 5 '12 at 8:19









          bmubmu

          22.1k87693




          22.1k87693

























              19














              Use sphinx-argparse extension:



              http://sphinx-argparse.readthedocs.org/en/latest/






              share|improve this answer



















              • 1





                Excellent. Is there a way to have the "usage" block treated differently? For me, having it as a literal block isn't quite right.

                – orome
                Jan 21 '14 at 21:43






              • 1





                And while I'm at it, it would be nice of the output for options matched what .. option:: produces: flags only (no default indicated), aligned all the way to the left with less indentation for the description, and changing the first letter to caps and adding a period at the end if one is not already there (since the idiom for --help is to omit these and use all lowercase). Also perhaps flag entries that match the help help output more closely (e.g. -cols [COL [COL ...]] rather than just cols), since all the text is written in that context.

                – orome
                Jan 21 '14 at 22:26











              • Seems to have an error: pastebin.com/jXAz1qHw

                – Martin Thoma
                Oct 20 '14 at 15:34
















              19














              Use sphinx-argparse extension:



              http://sphinx-argparse.readthedocs.org/en/latest/






              share|improve this answer



















              • 1





                Excellent. Is there a way to have the "usage" block treated differently? For me, having it as a literal block isn't quite right.

                – orome
                Jan 21 '14 at 21:43






              • 1





                And while I'm at it, it would be nice of the output for options matched what .. option:: produces: flags only (no default indicated), aligned all the way to the left with less indentation for the description, and changing the first letter to caps and adding a period at the end if one is not already there (since the idiom for --help is to omit these and use all lowercase). Also perhaps flag entries that match the help help output more closely (e.g. -cols [COL [COL ...]] rather than just cols), since all the text is written in that context.

                – orome
                Jan 21 '14 at 22:26











              • Seems to have an error: pastebin.com/jXAz1qHw

                – Martin Thoma
                Oct 20 '14 at 15:34














              19












              19








              19







              Use sphinx-argparse extension:



              http://sphinx-argparse.readthedocs.org/en/latest/






              share|improve this answer













              Use sphinx-argparse extension:



              http://sphinx-argparse.readthedocs.org/en/latest/







              share|improve this answer












              share|improve this answer



              share|improve this answer










              answered Sep 5 '13 at 10:54









              ribozzribozz

              41647




              41647








              • 1





                Excellent. Is there a way to have the "usage" block treated differently? For me, having it as a literal block isn't quite right.

                – orome
                Jan 21 '14 at 21:43






              • 1





                And while I'm at it, it would be nice of the output for options matched what .. option:: produces: flags only (no default indicated), aligned all the way to the left with less indentation for the description, and changing the first letter to caps and adding a period at the end if one is not already there (since the idiom for --help is to omit these and use all lowercase). Also perhaps flag entries that match the help help output more closely (e.g. -cols [COL [COL ...]] rather than just cols), since all the text is written in that context.

                – orome
                Jan 21 '14 at 22:26











              • Seems to have an error: pastebin.com/jXAz1qHw

                – Martin Thoma
                Oct 20 '14 at 15:34














              • 1





                Excellent. Is there a way to have the "usage" block treated differently? For me, having it as a literal block isn't quite right.

                – orome
                Jan 21 '14 at 21:43






              • 1





                And while I'm at it, it would be nice of the output for options matched what .. option:: produces: flags only (no default indicated), aligned all the way to the left with less indentation for the description, and changing the first letter to caps and adding a period at the end if one is not already there (since the idiom for --help is to omit these and use all lowercase). Also perhaps flag entries that match the help help output more closely (e.g. -cols [COL [COL ...]] rather than just cols), since all the text is written in that context.

                – orome
                Jan 21 '14 at 22:26











              • Seems to have an error: pastebin.com/jXAz1qHw

                – Martin Thoma
                Oct 20 '14 at 15:34








              1




              1





              Excellent. Is there a way to have the "usage" block treated differently? For me, having it as a literal block isn't quite right.

              – orome
              Jan 21 '14 at 21:43





              Excellent. Is there a way to have the "usage" block treated differently? For me, having it as a literal block isn't quite right.

              – orome
              Jan 21 '14 at 21:43




              1




              1





              And while I'm at it, it would be nice of the output for options matched what .. option:: produces: flags only (no default indicated), aligned all the way to the left with less indentation for the description, and changing the first letter to caps and adding a period at the end if one is not already there (since the idiom for --help is to omit these and use all lowercase). Also perhaps flag entries that match the help help output more closely (e.g. -cols [COL [COL ...]] rather than just cols), since all the text is written in that context.

              – orome
              Jan 21 '14 at 22:26





              And while I'm at it, it would be nice of the output for options matched what .. option:: produces: flags only (no default indicated), aligned all the way to the left with less indentation for the description, and changing the first letter to caps and adding a period at the end if one is not already there (since the idiom for --help is to omit these and use all lowercase). Also perhaps flag entries that match the help help output more closely (e.g. -cols [COL [COL ...]] rather than just cols), since all the text is written in that context.

              – orome
              Jan 21 '14 at 22:26













              Seems to have an error: pastebin.com/jXAz1qHw

              – Martin Thoma
              Oct 20 '14 at 15:34





              Seems to have an error: pastebin.com/jXAz1qHw

              – Martin Thoma
              Oct 20 '14 at 15:34











              4














              You can use sphinxcontrib.autoprogram. pip install sphinxcontrib-autoprogram, then put 



              extensions += ['sphinxcontrib.autoprogram']


              in your conf.py. To document command cli.py by importing cli with the argparse parser object parser (which can be a Python expression, like a function get_parser()), use



              .. autoprogram:: cli:parser
              
   :prog: cli.py





              share|improve this answer




























                4














                You can use sphinxcontrib.autoprogram. pip install sphinxcontrib-autoprogram, then put 



                extensions += ['sphinxcontrib.autoprogram']


                in your conf.py. To document command cli.py by importing cli with the argparse parser object parser (which can be a Python expression, like a function get_parser()), use



                .. autoprogram:: cli:parser
                
   :prog: cli.py





                share|improve this answer


























                  4












                  4








                  4







                  You can use sphinxcontrib.autoprogram. pip install sphinxcontrib-autoprogram, then put 



                  extensions += ['sphinxcontrib.autoprogram']


                  in your conf.py. To document command cli.py by importing cli with the argparse parser object parser (which can be a Python expression, like a function get_parser()), use



                  .. autoprogram:: cli:parser
                  
   :prog: cli.py





                  share|improve this answer













                  You can use sphinxcontrib.autoprogram. pip install sphinxcontrib-autoprogram, then put 



                  extensions += ['sphinxcontrib.autoprogram']


                  in your conf.py. To document command cli.py by importing cli with the argparse parser object parser (which can be a Python expression, like a function get_parser()), use



                  .. autoprogram:: cli:parser
                  
   :prog: cli.py






                  share|improve this answer












                  share|improve this answer



                  share|improve this answer










                  answered Aug 9 '16 at 2:37









                  asmeurerasmeurer

                  58.8k17113188




                  58.8k17113188






























                      draft saved

                      draft discarded




















































                      Thanks for contributing an answer to Stack Overflow!


                      • Please be sure to answer the question. Provide details and share your research!

                      But avoid …



                      • Asking for help, clarification, or responding to other answers.

                      • Making statements based on opinion; back them up with references or personal experience.


                      To learn more, see our tips on writing great answers.




                      draft saved


                      draft discarded














                      StackExchange.ready(
                      function () {
                      StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f10886841%2fsphinx-and-argparse-autodocumenting-command-line-scripts%23new-answer', 'question_page');
                      }
                      );

                      Post as a guest















                      Required, but never shown





















































                      Required, but never shown














                      Required, but never shown












                      Required, but never shown







                      Required, but never shown

































                      Required, but never shown














                      Required, but never shown












                      Required, but never shown







                      Required, but never shown







                      -

                      Popular posts from this blog

                      Monofisismo

                      Image
                      Monofisismo (do grego: monos - "único, singular" e physis - "natureza") é o ponto de vista cristológico que defende que, depois da união do divino e do humano na encarnação histórica, Jesus Cristo, como encarnação do Filho ou Verbo ( Logos ) de Deus, teria apenas uma única "natureza", a divina, e não uma síntese de ambas. O monofisismo é contraposto pelo diofisismo (ou "diafisismo"), que defende que Jesus preservou em si as duas naturezas. Historicamente, o monofisismo se refere primordialmente à posição dos que (especialmente no Egito e, em menor grau, na Síria) rejeitaram as decisões do Concílio de Calcedônia em 451 (o quarto concílio ecumênico). Os membros mais moderados entre eles, porém, defendem a teologia "miafisita", que se tornou a oficial para as Igrejas Ortodoxas Orientais. Muitos ortodoxos orientais, porém, rejeitam essa classificação, mesmo como um termo genérico, mas ele é amplamente utilizado na literatura históri...
                      Read more

                      Angular Downloading a file using contenturl with Basic Authentication

                      Image
                      0 I have a contentUrl when user clicks on that,file should be downloaded. If I try to browse the contentUrl in the browser it asks for Userid and password.I believe this is Basic Authentication.I dont want user to enter UserId and Password so I am passing it Authorization(Please see below code). Url looks some thing like this: http://XXX.XXX.XX.XXX:8080/flowable-rest/service/runtime/tasks/90875/attachments/90555/content let username : string = 'admin'; let pwd : string = 'test'; let headers = new Headers(); headers.set('Accept', 'text/json'); headers.append('Content-Type', 'application/json'); headers.set('Access-Control-Allow-Origin', '*'); headers.set('Access-Control-Allow-Methods','POST, GET, OPTIONS, PUT, DELETE'); head...
                      Read more

                      Olmecas

                      Image
                      Monumento 1, uma das quatro cabeças colossais encontradas em La Venta, com altura aproximada de 3 metros Olmecas é a designação do povo e da civilização que estiveram na origem da antiga cultura pré-colombiana da Mesoamérica e que se desenvolveram nas regiões tropicais do centro-sul do atual México durante o pré-clássico, próximo de onde hoje estão localizados os estados mexicanos de Veracruz e Tabasco, no Istmo de Tehuantepec, numa zona designada área nuclear olmeca. A cultura olmeca floresceu nesta região aproximadamente entre 1500 e 400 a.C., [ 1 ] e crê-se que tenha sido a civilização-mãe de todas as civilizações mesoamericanas que se desenvolveram posteriormente. [ 2 ] No entanto, desconhece-se a sua exacta filiação étnica, ainda que existam numerosas hipóteses colocadas para tentar resolver esta questão. O etnónimo olmeca foi cunhado pelos arqueólogos do século XX, e não devem confundir-se com os muito posteriores olmecas-xicalancas que ocuparam vários locais do México...
                      Read more