Documentation for PyFR

[Gavin Wiggins]

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?

[Vincent, Peter E]

Hi Gavin,

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

Peter

Professor of Computational Fluid Dynamics and EPSRC Fellow
Department of Aeronautics
Imperial College London
South Kensington
London
SW7 2AZ
UK

On 24 Sep 2020, at 15:45, 'Gavin Wiggins' via PyFR Mailing List <pyfrmai...@googlegroups.com> wrote:

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?

--
You received this message because you are subscribed to the Google Groups "PyFR Mailing List" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pyfrmailingli...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/pyfrmailinglist/c12ba651-f8cd-4a51-8698-af7e41d31625n%40googlegroups.com.

[Gavin Wiggins]

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?

[Gavin Wiggins]

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.

[Gavin Wiggins]

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.

[Vincent, Peter E]

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

Professor of Computational Fluid Dynamics and EPSRC Fellow
Department of Aeronautics
Imperial College London
South Kensington
London
SW7 2AZ
UK

On 24 Sep 2020, at 20:04, 'Gavin Wiggins' via PyFR Mailing List <pyfrmai...@googlegroups.com> wrote:

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>

To view this discussion on the web, visit https://groups.google.com/d/msgid/pyfrmailinglist/2a76dbf4-a772-4d2b-bfbf-9785c6d51bcen%40googlegroups.com.
<screenshot.png>

[Vincent, Peter E]

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

Professor of Computational Fluid Dynamics and EPSRC Fellow
Department of Aeronautics
Imperial College London
South Kensington
London
SW7 2AZ
UK

To view this discussion on the web, visit https://groups.google.com/d/msgid/pyfrmailinglist/6108cacf-e25b-424b-bc10-98de40070a9cn%40googlegroups.com.

[Gavin Wiggins]

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.