Portray: python documentation generator

Backstory

Shortly after my previous post, I realized that a Hello world checkpoint for a Python project should include some more things. One of them being a documentation setup, which I will describe in this post.

In my corporate life, I work with Sphinx, which I don’t like too much. =) This is both ironic and sad because it was originally created for Python documentation. It feels too complex and tedious, which leads to the tool hogging the focus rather than the purpose it was meant for. The idiom “tail wagging the dog” comes to mind. I have also used Doxygen previously which was a little less complex.

I tried a few alternatives, such as MkDocs and pydoctor. These are useful and certainly more desirable than Sphinx or Doxygen. However, they still involve many configuration steps, which I find problematic, because it also means more ways for things to break.

Can you imagine how foolish it feels when you cannot work on developing the actual software because you have to instead fix the tool setup?

Then I discovered Portray, mentioned incidentally in this blog post Python auto-generated documentation — 3 tools that will help document your project by Bartlomiej Skwira.

Portray setup

The portray setup involves:

• Install the portray module
  by either:

  • pip install portray or
  • mentioning it as a dependency in the project’s pyproject.toml (preferred)

• Execute portray
  specifying one of the output targets, such as:

  • portray in_browser: hosts the documentation on a local server (at localhost:8000 by default) and loads it in the default browser.
  • portray on_github_actions: if the project is on Github, runs a Github Action to publish the documentation to Github Pages.

That’s it!

Portray automatically includes modules and module structure, classes, methods, etc., their corresponding source codes, documentation from docstrings into the documentation.

Additional options and configurations

While Portray’s out-of-the-box settings are already impressive, it also provides additional options and configurations:

• Manual documents in markdown format: Portray automatically reads a README.md file and any markdown files in a docs folder inside the project’s root directory, generates the HTML pages, and includes them in the generated documentation.

• Applying themes: MkDocs themes can be easily applied to the generated documentation.

Further configuration options are described in the documentation.

Demo and Further Remarks

I created a short demo video showing the portray setup and use in my hobby project.

Earlier this week, I started the Coursera course User Experience Research and Design Specialization. One of the optional assignments is to share examples of Good UX and Bad UX from one’s personal experiences. I am so happy with portray UX that I’m going to submit it as my example of good UX.

Portray appears to be not very well known in the Python community. I hope you would consider giving it some of the love it deserves by trying it in your own projects.