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.

3 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?

3 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.

1 Like

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

1 Like

The guide is now live at
https://paraview.readthedocs.io/en/latest/index.html#

Preferred URL:
https://docs.paraview.org/en/latest/

The git repo is:
https://gitlab.kitware.com/paraview/paraview-docs/

Maybe a silly question, but are we planning to update this new guide only and leave the LaTeX guide alone?

Yes, the LaTex guide will be marked as deprecated.

No, we always want the Getting Started guide to be with ParaView. If a person tries to run ParaView on a LAN that does not connect to the outside world, we want the Getting Started guide to be available.

Just a quick remark, there is ads on the site. Do we want that ?

And, just because I am paranoid, what if readthedocs goes away? How do we recover our Users Guide?

Note, creation of PDFs is still supported and the ParaView binaries will include appropriate PDFs.

I’m OK moving the tutorials to ReadTheDocs.

ReadTheDocs is just the host – we can generate the docs locally and host ourselves. We may still consider that which would also avoid the ads etc. But this gets the ball rolling with minimal effort.

1 Like

The Getting Started guide is currently a Word document exported to PDF. We won’t transition that as it would be difficult or impossible to create in Markdown.