docs/reST/tut needs to be classified

[rumia0601]

I know there are some tutorials at docs/reST/tut with different writers. However, every tutorials are putted in single directory. I think every files in docs/reST/tut should be divided to sub-directories by writter's ID. Then it will looks like arranged.

[illume]

Good idea.

[illume]

One issue we need to think about is older URLs. How do we make sure the old web based URLs are redirected to the new ones? Can the Sphinx tool do this, or do we need to do this ourselves somehow. If Sphinx can't do this, we could add some redirects on the website. But we'd need a mapping of old_url -> new_url.

How do different languages folders fit in here? Is there a Sphinx recommended way to do this? What are other projects doing? tut/en, tut/ko, tut/no etc?

What about ordering by topic instead? From a users perspective it may be nicer.

[illume]

Currently docs/reST/tut/ has these files in there. Note all the image files.

CameraIntro.rst
ChimpLineByLine.rst
DisplayModes.rst
ImportInit.rst
MakeGames.rst
MoveIt.rst
PygameIntro.rst
SpriteIntro.rst
SurfarrayIntro-rest
SurfarrayIntro.rst
camera_average.jpg
camera_background.jpg
camera_green.jpg
camera_hsv.jpg
camera_mask.jpg
camera_rgb.jpg
camera_thresh.jpg
camera_thresholded.jpg
camera_yuv.jpg
chimp.py.rst
chimpshot.gif
common.txt
intro_ball.gif
intro_blade.jpg
intro_freedom.jpg
newbieguide.rst
surfarray.png
surfarray_allblack.png
surfarray_flipped.png
surfarray_redimg.png
surfarray_rgbarray.png
surfarray_scaledown.png
surfarray_scaleup.png
surfarray_soften.png
surfarray_striped.png
surfarray_xfade.png
tom_basic.png
tom_event-flowchart.png
tom_formulae.png
tom_games2.rst
tom_games3.rst
tom_games4.rst
tom_games5.rst
tom_games6.rst
tom_radians.png

[illume]

MyreMylarLa on discord mentioned this extension: https://github.com/sphinx-contrib/redirects This requires Javascript however.

We need a sphinx native extension(like 'redirects'), and a mapping for the website.

• For local documentation bookmarks (on the users own device) it would be nice to use something like this extension.
• For search engines, we'd need to implement a mapping.

[illume]

There is an internationalization guide for sphinx. http://www.sphinx-doc.org/en/master/usage/advanced/intl.html

However this works on translatable strings instead. I don't think it's suitable for whole tutorial documents.

[illume]

Here's how the pygame zero does it: https://pygame-zero.readthedocs.io/en/stable/contributing.html#translating They have one github repository per translation, using a fork model, and link to the other translations from the main english translation.

I'm not sure how successful that worked out, because I can't see any translations linked there yet. It's not clear how to find the other translations.

Additionally, some content is original in languages other than English. I'm not sure how this model would support this. For example: there are Polish, German, and soon Korean articles that don't exist in English.

[illume]

Mu-editor has "Internationalisation of Mu" https://mu.readthedocs.io/en/latest/translations.html

However, it doesn't seem to be a very good idea for tutorials and long form documents.

[illume]

Folder structure now:

11:52:32-rene~/dev/pygame/pygame/docs/reST (master)$ tree
.
├── Makefile
├── _static
│   ├── pygame.ico
│   ├── pygame_tiny.png
│   ├── reset.css
│   └── tooltip.css
├── _templates
│   ├── header.h
│   └── sourcelink.html
├── c_api
│   ├── base.rst
│   ├── bufferproxy.rst
│   ├── cdrom.rst
│   ├── color.rst
│   ├── display.rst
│   ├── event.rst
│   ├── freetype.rst
│   ├── mixer.rst
│   ├── rect.rst
│   ├── rwobject.rst
│   ├── slots.rst
│   ├── surface.rst
│   ├── surflock.rst
│   └── version.rst
├── c_api.rst
├── common.txt
├── conf.py
├── ext
│   ├── __init__.py
│   ├── boilerplate.py
│   ├── customversion.py
│   ├── edit_on_github.py
│   ├── headers.py
│   ├── indexer.py
│   └── utils.py
├── filepaths.rst
├── index.rst
├── ref
│   ├── bufferproxy.rst
│   ├── camera.rst
│   ├── cdrom.rst
│   ├── code_examples
│   │   ├── draw_module_example.png
│   │   ├── draw_module_example.py
│   │   ├── joystick_calls.png
│   │   └── joystick_calls.py
│   ├── color.rst
│   ├── common.txt
│   ├── cursors.rst
│   ├── display.rst
│   ├── draw.rst
│   ├── event.rst
│   ├── examples.rst
│   ├── font.rst
│   ├── freetype.rst
│   ├── gfxdraw.rst
│   ├── image.rst
│   ├── joystick.rst
│   ├── key.rst
│   ├── locals.rst
│   ├── mask.rst
│   ├── math.rst
│   ├── midi.rst
│   ├── mixer.rst
│   ├── mouse.rst
│   ├── music.rst
│   ├── overlay.rst
│   ├── pixelarray.rst
│   ├── pixelcopy.rst
│   ├── pygame.rst
│   ├── rect.rst
│   ├── scrap.rst
│   ├── sndarray.rst
│   ├── sprite.rst
│   ├── surface.rst
│   ├── surfarray.rst
│   ├── tests.rst
│   ├── time.rst
│   ├── touch.rst
│   └── transform.rst
├── themes
│   └── classic
│       ├── elements.html
│       ├── page.html
│       ├── static
│       │   └── pygame.css_t
│       └── theme.conf
└── tut
    ├── CameraIntro.rst
    ├── ChimpLineByLine.rst
    ├── DisplayModes.rst
    ├── ImportInit.rst
    ├── MakeGames.rst
    ├── MoveIt.rst
    ├── PygameIntro.rst
    ├── SpriteIntro.rst
    ├── SurfarrayIntro-rest
    ├── SurfarrayIntro.rst
    ├── camera_average.jpg
    ├── camera_background.jpg
    ├── camera_green.jpg
    ├── camera_hsv.jpg
    ├── camera_mask.jpg
    ├── camera_rgb.jpg
    ├── camera_thresh.jpg
    ├── camera_thresholded.jpg
    ├── camera_yuv.jpg
    ├── chimp.py.rst
    ├── chimpshot.gif
    ├── common.txt
    ├── intro_ball.gif
    ├── intro_blade.jpg
    ├── intro_freedom.jpg
    ├── newbieguide.rst
    ├── surfarray.png
    ├── surfarray_allblack.png
    ├── surfarray_flipped.png
    ├── surfarray_redimg.png
    ├── surfarray_rgbarray.png
    ├── surfarray_scaledown.png
    ├── surfarray_scaleup.png
    ├── surfarray_soften.png
    ├── surfarray_striped.png
    ├── surfarray_xfade.png
    ├── tom_basic.png
    ├── tom_event-flowchart.png
    ├── tom_formulae.png
    ├── tom_games2.rst
    ├── tom_games3.rst
    ├── tom_games4.rst
    ├── tom_games5.rst
    ├── tom_games6.rst
    └── tom_radians.png

10 directories, 123 files

[illume]

The cpython documentation uses this procedure: https://www.python.org/dev/peps/pep-0545/#new-translation-procedure

They already had two separate translation git repos (French and Japanese). One of them is here:

• https://github.com/python/python-docs-fr
• https://github.com/python/python-docs-ja
• https://github.com/python/python-docs-ko (not started)

They seem to be based on translation files, and they do not use management software like Transiflex. It's not clear to me if they have original documentation mixed in.

[illume]

One problem with having whole translations in separate folders is that the image paths and linking need to be changed. Maybe not such a bad thing.

docs/reST/tut/en/ChimpLineByLine/ChimpLineByLine.rst
docs/reST/tut/en/ChimpLineByLine/image1.png
docs/reST/tut/de/SchimpanseZeileFürZeile/SchimpanseZeileFürZeile.rst

Then things in "de/SchimpanseZeileFürZeile/" folder can reference images in the "../en/ChimpLineByLine"

Note that this way is not readable by people using the folder structure... (pretending you don't know English for one moment). As the filename is still "ChimpLineByLine-en.rst".

docs/reST/tut/ChimpLineByLine-en.rst
docs/reST/tut/ChimpLineByLine-de.rst
docs/reST/tut/ChimpLineByLine-ko.rst

Additionally, that is quite cluttered having them all in the same folder.

Note, the "en" is not a special case. It is alongside all the other locale/langs.

[illume]

Talking with a couple of people who work in translation... They are happy to do documents using things like google docs, open office and word. Or working inside website systems when the text is small. They don't like long documents inside some translation websites because they are mainly meant for smaller pieces of text. None had heard of Sphinx or restructured text. One had heard of github but had never edited anything on there.

[illume]

Currently our docs html output does not contain the human language of the page in the html meta data. Need to investigate how this can be included.