Elvas Tower: Portable workbench for building the manual (old/obsolete) - Elvas Tower

Jump to content

Posting Rules

All new threads will be started by members of the Open Rails team, Staff, and/or Admins. Existing threads started in other forums may get moved here when it makes sense to do so.

Once a thread is started any member may post replies to it.
  • 3 Pages +
  • 1
  • 2
  • 3
  • You cannot start a new topic
  • You cannot reply to this topic

Portable workbench for building the manual (old/obsolete) Rate Topic: -----

#1 User is offline   YoRyan 

  • Conductor
  • Group: Status: Active Member
  • Posts: 391
  • Joined: 19-February 20
  • Gender:Male
  • Location:California, United States
  • Simulator:Open Rails/unstable
  • Country:

Post icon  Posted 31 July 2020 - 01:08 PM

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.


#2 User is offline   xavivilla 

  • Fireman
  • Group: Status: Active Member
  • Posts: 197
  • Joined: 12-May 12
  • Gender:Male
  • Simulator:Open Rails - RailWorks
  • Country:

Posted 31 July 2020 - 02:27 PM

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.

#3 User is offline   YoRyan 

  • Conductor
  • Group: Status: Active Member
  • Posts: 391
  • Joined: 19-February 20
  • Gender:Male
  • Location:California, United States
  • Simulator:Open Rails/unstable
  • Country:

Posted 05 September 2020 - 11:02 AM

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.

#4 User is offline   Csantucci 

  • Member, Board of Directors
  • Group: Status: Elite Member
  • Posts: 6,986
  • Joined: 31-December 11
  • Gender:Male
  • Country:

Posted 05 September 2020 - 12:28 PM

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

#5 User is offline   YoRyan 

  • Conductor
  • Group: Status: Active Member
  • Posts: 391
  • Joined: 19-February 20
  • Gender:Male
  • Location:California, United States
  • Simulator:Open Rails/unstable
  • Country:

Posted 05 September 2020 - 12:32 PM

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

#6 User is offline   James Ross 

  • Open Rails Developer
  • Group: Status: Elite Member
  • Posts: 5,488
  • Joined: 30-June 10
  • Gender:Not Telling
  • Simulator:Open Rails
  • Country:

Posted 11 September 2020 - 03:32 PM

View PostYoRyan, 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.

#7 User is offline   Csantucci 

  • Member, Board of Directors
  • Group: Status: Elite Member
  • Posts: 6,986
  • Joined: 31-December 11
  • Gender:Male
  • Country:

Posted 11 September 2020 - 11:13 PM

View PostJames 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.

#8 User is offline   RR1 

  • Hostler
  • Group: Status: Active Member
  • Posts: 74
  • Joined: 03-March 13
  • Gender:Male
  • Simulator:OR
  • Country:

Posted 12 September 2020 - 05:03 AM

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.

#9 User is offline   YoRyan 

  • Conductor
  • Group: Status: Active Member
  • Posts: 391
  • Joined: 19-February 20
  • Gender:Male
  • Location:California, United States
  • Simulator:Open Rails/unstable
  • Country:

Posted 23 September 2020 - 12:10 AM

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.

#10 User is offline   Csantucci 

  • Member, Board of Directors
  • Group: Status: Elite Member
  • Posts: 6,986
  • Joined: 31-December 11
  • Gender:Male
  • Country:

Posted 16 March 2021 - 01:06 AM

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?

  • 3 Pages +
  • 1
  • 2
  • 3
  • You cannot start a new topic
  • You cannot reply to this topic

1 User(s) are reading this topic
0 members, 1 guests, 0 anonymous users