3

I have a python project that I want to create the documentation...

In this documentation, it is crucial allowing embedding images. Also, I would like to not create a separate file. In others words: the *.py file would contain both the script and the documentation (that has images embed).

Of course, later on this *.py would be processed by a tool to create a markdown or HTML report.

I took a look at mkDocs and Sphinx, but I am not sure if they support these requirements.

Does anyone know how to do something similar with these tools (or another)?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
guilhermecgs
  • 2,913
  • 11
  • 39
  • 69
  • 1
    What do you mean by "embed"? Encode image in Base64? – mzjn Jan 25 '18 at 15:37
  • Just a link to the image file. When the (html, md) file is opened in a browser, the browser should render the image – guilhermecgs Jan 25 '18 at 15:40
  • 1
    Then what do you mean by "I would like to not create a separate file"? – mzjn Jan 25 '18 at 15:41
  • sorry for the confusion: I am not familiar with all documentation tools. In my mind, if I have a "source.py" , one common use case is to manually create a source.md file containing all the documentation. In this case, there will be two files. What I want is source.py containing both the code and the documentation, image links and etc. After running a external tool command, the source.md(html) would be generated – guilhermecgs Jan 25 '18 at 15:48
  • 1
    You can add documentation as docstrings in Python modules. With Sphinx, these docstrings can be extracted and included in the HTML output. See http://www.sphinx-doc.org/en/stable/ext/autodoc.html. – mzjn Jan 25 '18 at 15:51

1 Answers1

3

As @mzjn suggested, you can write docstrings in your python modules. Docstrings may be valid reStructuredText. reStructuredText syntax supports inline images. The given file name of the image must be either relative to the source file or absolute to the documentation root. You must have a separate image file.

To build docs with Sphinx, you will need a set of reStructuredText files from which you build your documentation. You can use Sphinx quick-start to generate the .rst source files.

Once you have written your docstrings, and have created .rst source files, and configured your conf.py to use the autodoc module to pull in your module's docstrings, then you can use Sphinx and its autodoc module to build documentation in supported formats, including HTML.

Note that images must be in a supported format for the builder's output.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57