Documentation for PyFR

General
1

In the PyFR GitHub repository there is a “doc” directory. It looks like this directory is for building the documentation with Sphinx. But where is the documentation hosted? Is it just the main PyFR website at http://www.pyfr.org?

2

Hi Gavin,

Yes, the html version of the docs are hosted on the PyFR website.

Peter

3

I’m trying to build the Sphinx documentation from within the doc folder using make html but I get the following error:

Could not import extension tikz (exception: cannot import name ‘Directive’ from ‘sphinx.util.compat’ (/Users/gavinw/Desktop/GitHub/wigging/PyFR/venv/lib/python3.7/site-packages/sphinx/util/compat.py))
make: *** [html] Error 2

Any suggestions on how to build the docs locally?

4

Using ‘sphinxcontrib.tikz’ instead of ‘tikz’ fixes the problem and I’m able to build the site. Although some warnings appear about deprecated highlighting. The built Sphinx site looks nothing like your website at pyfr.org (see attached screenshot). You must be doing some post-Sphinx steps and CSS after the build.

screenshot.png
screenshot.png2644×1924 690 KB

5

I highly recommend using Read the Docs for the PyFR documentation. It will make it easier for others (including myself) to contribute to the documentation. It can be setup to automatically update the documentation website from the GitHub repo when new changes are pushed. I did this for one of my personal projects (https://chemics.readthedocs.io) and it works well.

6

Hi Gavin,

Yes, on each release I compile the docs and then drop the /html folder into the website, that has code to automatically integrate it (and apply styles that match the rest of the website). The content is identical, however.

Thanks

Peter

7

Hi Gavin,

Thanks for the suggestions. Our process around the docs is about 8 years old, so it may well benefit from a bit of an overhaul.

I’ll take a look at Read the Docs and possible Github based workflows and get back to you (it may take me a week or so due to the start of term). Maybe we can then have a call to discuss options and get your feedback?

In the interim, would you be able to submit a new PR that simply changes the format of the README to .md and also fixes the typo in the .ini file for the incompressible cylinder example case? We can then get those parts in straight away.

Thanks

Peter

8

I submitted Pull Requests for the README and the typo in the ini file.

I also started a new docs build using the latest version of Sphinx. I’ll share that as a draft Pull Request once it’s ready.