[YoRyan]

2022 update: Check out the new Visual Studio Code development container available in the master repository.
____________________

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://youngryan.co...h_2020-09-05.7z

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).
  
• 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.

[Csantucci]

I'm getting a problem trying to generate the manual. I enter "make html" in the command prompt window, Sphynx starts, but after some lines I get a Sphynx error telling me that contents.rst can't be found. In fact this file is not included in the Documentation pack. To proceed I have to manually generate a dummy file with such name. Am I doing something wrong?

[xavivilla]

I had this problem with the version of Sphynx that I have installed on my computer, I managed to generate the manual by making a copy of the index.rst file and renaming it contents.rst. But with the portable version published here and running Open Cmd.bat it is not necessary to have the contents.rst file to generate the manual.

[Csantucci]

Thank you, I have only to find out where I unpacked Ryan's pack...

[xavivilla]

Wherever you have Ryan's package, put all the .rst files and associated "images" directory, run Open Cmd.bat, type "make html" or "make pdf" as you wish to generate the manual

[Csantucci]

That's OK now for the html version, thank you. The "make pdf" command doesn't work here though: it writes "Builder name not registered or available through entry point".
"make latexpdf" doesn't work either ("the package latexmk could not be installed"). I attach the logfile
 latexmk.log.txt (408bytes)
Number of downloads: 415

[xavivilla]

The first time I ran "make pdf" the firewall asked me for internet access and I installed a latex package through the cmd window. Then I generate the latex file and later the pdf file.
From what I see in the attached log file, you have not been able to connect to the server (it seems that it has not responded and it sends you a 404 error)
Try again later and hopefully the server where the package to download is working.