[YoRyan]

Hi all,

As there has been a lot of interest in contributing to our manual, which is written in reStructuredText and has to be processed by Sphinx, I thought I'd share a "workbench" I made to make the process of building it much easier: https://drive.google...iew?usp=sharing

It includes portable versions of all of the software packages you need to build the HTML and PDF versions of the manual: WinPython, Sphinx, Strawberry Perl, and MiKTeX.

To use it,

• Extract the archive with 7zip (beware, the final size is 1.5 GB!). Your destination must not have any spaces or non-ASCII characters in its full path.
  
• In Windows Explorer, navigate to the extracted directory and double-click on "Open Cmd.bat". This will open a Command Prompt window with all of the workbench's utilities made available in %PATH%.
  
• cd to the Source\Documentation\Manual directory in your Open Rails source tree (tip: You can drag and drop paths from Windows Explorer to the command line).
  
• In this directory, create the "version.py" file if it doesn't already exist. It should have the following contents:

  version = 'X'
  revision = '000'

• Run "make html" to produce an HTML manual, or "make latexpdf" to produce a PDF one.
  
• If the build is successful, the files will output to _build\html or _build\latex.

[xavivilla]

Thanks Ryan

Even having the tools installed on the pc, I will try its portable version that seems more current than the Pynton, Sphinx and MIKTeX versions than the ones I have.

[YoRyan]

In the unstable branch, there's been an update to the PDF build system that adds Perl as a dependency. I have uploaded a new, larger (1.5GB!) version of the workbench that includes a copy of Strawberry Perl.

[Csantucci]

Does this mean that to build the PDF of the manual a Perl version must be available?

[YoRyan]

Yes; the change was made in James Ross' new PR.

[James Ross]

YoRyan, on 05 September 2020 - 11:02 AM, said:

In the unstable branch, there's been an update to the PDF build system that adds Perl as a dependency. I have uploaded a new, larger (1.5GB!) version of the workbench that includes a copy of Strawberry Perl.

Wow, I wasn't expecting that dependency!

With any luck it won't be needed again after https://github.com/o...nrails/pull/277, which fixes a few other problems by updating the "make.bat" and "conf.py" to match the latest Sphinx's quickstart template.

[Csantucci]

James Ross, on 11 September 2020 - 03:32 PM, said:

With any luck it won't be needed again after https://github.com/o...ils/pull/277...

That's good, because setting up the environment to build the .pdf version of the manual was already complicated enough. I wonder how many people have that working.

[RR1]

I was using a Linux VM. No setup was required because everything needed was native to the Linux distribution I was using. Simply copy paste the .rst files from the Windows folder to the Linux Sphinx folder, run the make file and copy the resulting HTML and/or pdf output back to Windows.

YoRyan's package is self contained, no setup is required. I'm using that now.

[YoRyan]

Unfortunately Perl remains a dependency even after merging the new PR, so it looks like it's here to stay.

Also, now the "version.py" file is required to build the manual. Normally it is created by the "Build.cmd" CI script, but if you don't want to set up an entire build environment, you can also create it manually. I have inserted instructions into the master post.