Currently, the PAL documentation is built using reStructuredText, and built using Sphinx.
Installing this on Windows requires jumping through a few hoops, although I am aware it is possible to install Sphinx on the Windows Subsystem for Linux if necessary.
What I am looking for, is feedback from some other developers on whether not we should stick with Sphinx, or change to using another methodology.
Some options include switching to markdown, and using existing conversion tools to convert to html, or converting directly to html.
Some benefits of remaining with Sphinx includes the ability to have search which works within the offline documentation.
Note that regardless of the method chosen, the documentation will be updated to maintain consistent branding, i.e. header/footer will be similar/identical to the main site or alternately to generic help files.
Visit the Community page
Join our forums
Subscribe to our email newsletter
Subscribe with RSS
Follow us on Facebook
Follow us on LinkedIn
Follow us on Twitter
Follow us on Mastodon
Follow us on BlueSky
Unless you have a specific reason for switching to something else, I'd be inclined to leave it in it's current system, and just update the content/theme of it.
Any particular reason you say "Installing this on Windows requires jumping through a few hoops"?
As far as I see, all you need is Python and it's "Scripts" folder both on your
%PATH%, andpip(adding the Scripts folder to %PATH% is the only part not available as an install option with all current versions of Python, and that's easy to do for yourself), then runpip install sphinx, and you're good to go. You could even do this on a temporary basis with a Portable version of Python without too much difficulty.Also (and I realize this isn't really the place to raise theming objections) I have no love for the 'flat' themes everybody's going with nowadays, but on the other hand, I do understand the desire to keep a uniform appearance between the default platform theme, the main site, and the help documentation.
~3D1T0R
I'm inclined to leave it as is at this point, with updating of content and theming as well.
If desired, it appears we may be able to integrate the online manual with the rest of the site, rather than solo as it currently is.
I have to admit I didn't look closely into what was required, however at a quick glance it appeared quite involved. I've since discovered that it is trivial to install sphinx on my personal system using the Windows Subsytem for Linux.
Without speaking to the pros or cons of flat themes, regardless of the methodology used for documentation of PAL, I will be ensuring a uniform appearance as you've noted.