appwiki:sphinx

Sphinx Intro

  • Sphinx is an auto documentation generation python module tool for your source codes.
  • after download the source, build it for your python version in its directory
    python setup.py build
    • after its done, copy build/lib/sphinx directory to your prefered python module directory

Sphinx Usage

  • after sphinx in your python sys.path, and you are call it to check its installation success
    import sphinx
  • since you will use sphinx on all system, then I assume you run all the command in python shell, unless you want to follow Sphinx offical tutorial using system command shell to call function; Here, I will show all the calls in python shell.
    1. create doc project folder and change current working directory to it
    2. build rst configuration directory struction for generation docs
      # run quickstart method to make auto doc project directory structure, 
      #   same as sphinx-quickstart shell command in that current working directory
      from sphinx import quickstart
      quickstart.main()
      # then shows: Welcome to the Sphinx 1.2.2 quickstart utility. ... and questions
    3. edit conf.py and index.rst and create additional rst files for auto generation guide
    4. generate the docs into _build sub-folder, same as sphinx-build shell commands
      • shell version
        python /path_to_Sphinx/sphinx-build.py -b html . ./_build
      • python version
        # since the sys.argv is ['/path_to_Sphinx/sphinx-build.py', '-b', 'html', '.', './_build']
        import sphinx
        sphinx.main(['','-b','html','.','./_build']) # 1st arg is empty
        # you get same: Running Sphinx v1.2.2 .... and docs in _build folder

Sphinx for mel language

  • tips on use Sphinx for my mel project tools documentation.
  • to do
  • appwiki/sphinx.txt
  • Last modified: 2021/08/28 08:27
  • by ying