Documentation written for Sphinx

[GordCaswell]

Documentation is currently written for Sphinx.
Explore converting to Markdown or pure HTML for simpler handling on Windows.

[daemondevin]

I'd recommend using Markdown as it's a reliable means of converting markup to HTML. Seems like everyone is using it right now anyway (GitHub, CodePen, StackOverflow, etc.).

StackEdit.io/ seems like a lovely place to organize files and edit Markdown. You can even copy/paste any existing HTML markup into the left window pane and it'll still parse correctly. I've used it myself for a few things already.. not sure if you can somehow automate the already existing documentation with this site but it'd be worth looking into.

[3D1T0R]

I see no reason to stop using Sphinx, as it adds features that I don't think can be easily replaced (e.g. functioning search), and I'd personally stay away from MarkDown because there are so many flavours of it, it's hard to remember what works which way on which version of it.

Also I don't see why handling on windows needs to be simplified, it doesn't seem to be notably more difficult to me than it is on linux.
(Note: A good, up-to-date build of Python Portable would make this even easier & I'm experimenting with making one.)

[daemondevin]

I can easily write up a JavaScript file to handle the search functionality for the documentation. My coding background is heavily steeped in the arts of PHP, JavaScript, CSS, and HTML (and a few others like Java when I was experimenting with making Android Apps). I assure you JavaScript is very flexible and being that it is a client-side language, it can be deployed with a package for offline use by the end-user; which I believe is one of your main pitches on keeping the current method.

IMHO, Markdown may seem like an easy way to convert the current documentation, but I might just be bias in regards of my lack of familiarity with Sphinx and next-to-none experience with Python (any encounter I've had with Python was a brief moment owning a Linux based laptop and Notepad++; I went cross-eyed soon thereafter on both occasions ..lol.).

There are also plenty of alternatives in place of Markdown. For instance, I was hired by a gentleman who needed me to take all his content (which were simple text files) and code around that content making a dynamic website using mostly JavaScript wherever I was able to get away with it; I was to conserve on using server-side (PHP) code because he felt that if you can make the end-user's browser do the work, why make the server suffer? With that being said, you could essentially leave the documentation content in simple .txt files, probably better to use .htm though, and just use JavaScript to handle the dynamics of serving up the layout and composition of the content.

If you don't think I'm capable of coming up with such a "monumental" task like I just suggested, give a few of these links a visit and see the magic behind what JavaScript can really do:

• Codeblock w/ line numbers and highlight.js
• Context Menu (Right Click)
• Search Input
• 404 Error | Typing Effect in JS
• Tetris

If you're wondering, I wrote all of those Pens if you couldn't already tell. And yes, they are all heavily based on JavaScript (except the 404 Error one which is written in JQuery; which is just a JavaScript library anyway).

I wasn't trying to toot my own horn so please don't get the wrong impression. I was just merely trying to show the practicalities behind keeping it simple as well as show the qualifications to consider it. I believe this could be of some use if you're truly considering reviving the documentation.

[3D1T0R]

However, the existing Sphinx based solution already works quite well, and I see no reason to bother with writing a new search system just to facilitate a change from the fully functional, existing documentation method into something else, just because someone didn't see how to set up Sphinx.

FYI: Sphinx is a python module, and can be very easily installed with pip via pip install sphinx (or python -m pip install sphinx if Python's "Scripts" folder isn't on your PATH). It requires that Python's "Scripts" folder be on the PATH environment variable, which is easy to do, and then the existing make.bat file works perfectly.

Also, it really did come across as you 'tooting your own horn' demondevin. I have no difficulty believing that such a functionality could be created, but why bother when it's already working?

Why are you guys so keen on spending extra man-hours 'fixing' something that isn't broken at all?

Also, as I stated in my last comment, I intend to make a new PortableApps.com Format version of Python which would make this even easier.

[daemondevin]

I understand we aren't trying to reinvent the wheel. @GordCaswell was asking for people's opinions on the matter and I merely shared my thoughts. You obviously seem very well-versed when it comes to the current means of generating the documentation so maybe you should help @GordCaswell and steer him in the right direction.

I'm not saying that JavaScript or Markdown is the future; nor am I saying that Sphinx/Python is a dying breed either. It could be wise, however, to cater to the future development of the current method by using means that are more broadly used and documented themselves. As well as giving future developers that might take over the project a better means to know what they are getting into. Again, I'm probably just saying that because I myself do not know much about Sphinx/Python (Python, I'm sure, probably has a wide, dedicated community of users). There is an argument to be made that a developer needs to adapt to the current mainstream. For instance, PHP seems like it's on a steadily downward spiral while PHP-based frameworks such as Laravel or Symfony seem to be the up-and-coming frameworks to use; just like JQuery or ‎Ext JS are JavaScript-based frameworks (let's drive the point home with the fact that Facebook reinvented a version of PHP called Hack--this is just a different dialect if you will).

And you're right, I agree with you wholeheartedly, why should we fix something when it isn't even broken in the first place? However, if there's a means to better it without making someone smash their head into their monitor, than why not support their "man-hours" and work with them instead of trying to make them understand something they probably had no interest in learning in the first place?

[3D1T0R]

As far as me being "well-versed" in using the current system, after seeing this bug:

• I looked in the Other\Source\Manual directory and saw make.bat
• I looked at the contents of make.bat and saw that it called sphinx-build
• I searched for "sphinx-build install"
• I looked at the information at the first search result
• I already had an old (slightly modified) version of Portable Python, so I opened a command prompt through it
• I added the "Scripts" folder to my PATH variable (set PATH=%PATH%;X:\Path\To\Python\Scripts)
• I installed sphinx (pip install sphinx)
• I ran make.bat, which tells you what available commands it has.
  All of them worked except make doctest, which throws an error.
  I plan on checking it with older versions of PAL to see if it ever worked.

[3D1T0R]

@GordCaswell: Seeing as you've stated that you're "inclined to leave it as is" now, should this issue be closed?

[GordCaswell]

I'm going to hold off on closing the issue for the moment until I get feedback from @JohnTHaller regarding his preferences.

[3D1T0R]

Sounds good.

Btw, I've been wanting to fix the typo in the title of this issue. Any chance I could have the necessary privileges to edit issues?

[GordCaswell]

You should be able to now.

[3D1T0R]

Thanks.