Migrating ParaView Guide to Sphinx / ReadTheDocs

As I am updating the ParaView Guide and then Catalyst Guide to reflect the new Extract Generator related changes, I keep feeling we really need to migrate to a Sphinx-based documentation generation approach. A while ago I had manually converted the first chapter from the guide to sphinx to see how it renders. Here’s the result on readthedocs. It’s just a quick conversion so ignore all the keywords that have not been converted correctly from latex.

It’s much easier to update/access, reference, link in posts that the pdf users guide. What do people think? Is that a path we should consider?

Also the ParaView Guide and Catalyst Guide should really be combined. There’s no need for the two to exist independently.

2 Likes

Yes!

Hi !

Based on the above example I converted the rest of the chapters of the ParaView Guide.
Here is an online version on readthedocs .
Let me know if you have any comments or ideas for improvement.

Wow, that looks great!

This is awesome!

This looks fantastic, Christos! A few questions:

  • any ideas why the Search page doesn’t work?
  • do you know if readthedocs can be setup to monitor a git repo on gitlab? If so, we should create a new repo for this under the ParaVIew group on our gitlab and push this there.

I guess you mean the “Search Page” entry at the bottom of the landing page. I am not sure why, but since the search bar is also accessible on the top left, I removed this link to avoid any confusion.

The search bar on the top left should work :

Yes it can . I just tried with the same repository hosted on Kitware’s gitlab. I just needed to do a manual step [1] to enable automatic rebuilding of the docs on every push.

[1] https://docs.readthedocs.io/en/stable/webhooks.html#gitlab

2 Likes

That’s great!

Maybe we should create a new project named gitlab.kitware.com/paraview/paraview-docs and move this there. Eventually, we may want to move Getting Started guide Catalyst guide and Tutorial (s) to the same repo. Then we’d have a one-stop page to refer to for all reference material intended for ParaView and Catalyst users. What does everyone think?

2 Likes

I think it would be good and nice to have such consistency across documentation. Especially for ParaView which has many sources. If we can simplify it like you are suggesting, that would be great.

Neat. Let’s go ahead with that plan then.