Building the Docs locally (This is obsolete!)

EDIT:
This is obsolete as the docs (and PRs) are built fully automated in all languages.

Hey,

@Dannyps and I tried to build the docs manually to check formatting and spelling in our language. I must admit that there are several steps involved to build it sucessfully… I did it this way (on Windows 8.1 x64):

Before you start:
-get python and install it on your machine
-get sphinx (see also: http://sphinx-doc.org/tutorial.html)
-get ReadTheDocs Theme (optional)

  1. Get the complete SpongeDocs off Github (download *.zip here: GitHub - SpongePowered/SpongeDocs: Documentation for Sponge and its Implementations)
  2. Unzip in your workdir (anywhere you want; i prefer c:\spongedocs)
  3. Load all *.po and *.pot files off Transifex (in your preferred language)
  4. in CMD: pip install sphinx-intl (this will install sphinx intl)
  5. in CMD: navigate to your work-dir and run make gettext
  6. copy ReadTheDocstheme.zip to your /workdir/source folder
  7. edit conf.py in /workdir/source:
html_theme = 'readthedocs'
html_theme_path = ['.']
language='YOUR-LANGUAGE'
locale_dirs = ['../build/locale/']
  1. in CMD: sphinx-intl update -p build/locale -l YOUR-LANGUAGE --locale-dir FULL-PATH-TO-LOCALE-DIR
  2. replace all *.po in /locale/yourlanguage/ and *.pot in /locale with the ones you got off transifex
    (batch rename may come in handy… )
  3. in CMD: make html

Thats it. Your build is placed in workdir/build/html.
Go there and open index.html.

Sneakpeak/proof:

6 Likes

I still couldn’t do it :frowning: I’m missing something…

How far did you get and what exactly doesnt work?

I get to the end, but I get feeling it doesn’t access the po files… Right now I can’t do anything but I’ll look into it when I get home. Thanks

I clarified some things above… maybe you missed something i didnt point out clearly!?
I had to replace all *.pot and all *.po files to get it working. If it accesses the *.po files correctly *.mo files are generated next to them. If it helps i can provide you my complete folder with DE translations for reference. :smile:

1 Like

I would like to say that they have a client you can use! For Windows client Click Here (direct link). For all others do:

pip install transifex-client

Put the client in the root folder of your sponge project.

Then in your Command Console type:

tx init

Then leave the host blank (hit enter). When it prompts you for your username and password enter them.
*Please note: if the program failed to ask you for your username and password, please add them to the next file we are going to look at!

Now this should have created a folder named .tx. navigate to that folder and open the config file.
It should look like this:

If it does not, please edit it to match!

*Please note: If you signed up or in with github, you will have to go into your profile and do a password change. (This is just so your account is now in Transifex’s system.) You will then have to use your email address for the username field. (At least that’s how I had too, wont accept my username.)

Now we need to add a source language, so on line 5 add:

source_lang = en

Now go back to your console and type:

tx set --auto-remote https://www.transifex.com/projects/p/sponge-docs/

Let this run, it will take a few minutes to complete.

Finally in the console type:

tx pull -l <language_Code>

If you are unsure which language code you use, please visit the Transifex site, and select your language. When you select your language, look at the URL and the last bit would be your Language code. For example: For Dutch the link would be https://www.transifex.com/projects/p/sponge-docs/language/nl/. The language code for Dutch is nl.

For the *.po files I made a quick tool that I use myself. I just put it on GitHub if you want to look at it. all it does right now is something very simple, but that’s all i need it to do. :stuck_out_tongue:

@minecrell helped me out in IRC, but i appreciate your help! Will try this asap and report back.

EDIT: Wont try that if we switch to Crowdin und automated build is ready :smile:

EDIT2:
This is obsolete as the docs (and PRs) are built fully automated in all languages.

1 Like