You are here

Home » Forums » Development Forums » Portable App Development

PAL Documentation methodology

3 posts / 0 new
Log in or register to post comments
Last post
August 4, 2017 - 12:22am
#1
Gord Caswell
Gord Caswell's picture
Offline
Last seen: 3 days 13 hours ago
DeveloperModerator
Joined: 2008-07-24 18:46
PAL Documentation methodology

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.

Top
August 6, 2017 - 3:58pm
3D1T0R
3D1T0R's picture
Offline
Last seen: 1 year 6 months ago
Developer
Joined: 2006-12-29 23:48
Why?

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%, and pip (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 run pip 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

Top
August 10, 2017 - 1:44pm
(Reply to #2)
Gord Caswell
Gord Caswell's picture
Offline
Last seen: 3 days 13 hours ago
DeveloperModerator
Joined: 2008-07-24 18:46
Inclined to stay with it

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.

Top
Log in or register to post comments