Documentation contribution

Hello,
I was thinking of writing documentation(user) and did the setup required for it (Sphinx tools). Can anyone please suggest what should I start documenting first, I have seen some TODO in some pages, should I complete them or should I start writing documentation for topics that don’t exist yet? I also want to know what are the rules to follow while writing the documentation.

I found this instrutions for writers in the old wiki.

I have also come across some parts in Synfig which doesn’t have any documentation at all (ex- Filter Layer). In such case who should I contact so that I can find the accurate information (rather than making assumptions from trial and error myself).

I want to know what are the priorities in writing the documentation right now. And also any suggestions.

5 Likes

I think filling in the Main_Concepts>Layers section could be a good place to get started. Understanding Layers and how they are applied differently compared to other software is pretty essential to using Synfig, so it would be a big help to newcomers.

1 Like

I think you can read the documentation and check for inconsistencies, outdated images (if difference is relevant), nomenclature, …

And porting basic tutorials from Wiki to ReadTheDocs.

I think you’ll get used to doc collab and be more confident on it.

Well, you can ask here on Forums so anyone can try to contribute/help you. There are long-time users like @Svarov @ebarranko @Fadhilkwan and developers like @KonstantinDmitriev @ice0 @ankit @AnishG , and more recent and active contributors like @rodolforg (me) @FirasH @Keyikedalube .

3 Likes

The Layers. Half of them are not documented properly or at all. For example, ‘Halftone 2/3’ layers can be used to create nice textured effects but tough luck, use trial and error to figure out how to use them. Same for ‘Noise Distort’, one of the most powerful layer for creating all kinds of cool effects.

So personally, I would love to see all Synfig’s layers getting proper documentation first, because it’s a foundation of every composition. This is a pretty hard task though, because you’ll most likely have to read source code.

3 Likes

Hi @veermetri05! I am glad you’ve got interested in contributing to documentation!

First of all, I would like to mention that we are still in the process of migrating documentation from old MediaWiki to Sphinx. Please see this topic for details.

In short:

  • Currently we have many pages transferred to Sphinx already, but not all.
  • The procedure of transferring page is divided into two stages:
    1. Transfer basic text contents, formatting and images. Hyperlinks remaining broken at this point.
    2. Proofread and fix hyperlinks.
  • Currently for already transferred pages we did only stage 1. So all pages have broken hyperlinks. This is a good point where you can start contributing. I suggest to start with small PRs (i.e. fix links for page A).
  • You can track the progress of transferring pages on this Trello board. Bu this moment we have most important pages already transferred. I am still in process of sorting out remaining pages in “Queue” column.
5 Likes

P.S. We have a document that maps the list of old MediaWIki pages to the pages in the new documentation - Synfig documentation redirects - Google Docs

2 Likes

Thanks for organising the redirects, I will start fixing the broken links. I am thinking of creating a script (in Python) which would automatically fix the links.

Here’s my plan:
This is current link (broken).

`Linking <Linking>`__

So we can replace this to:

|Linking|

And then define the substitution,

.. |Linking| replace:: :ref:`linking`

I also need to create custom label for all sections within a page.
So,

`Blur Layer's 'size' parameter <Blur_Layer#Size>`

will be mapped to,

|Blur_Layer_Size|

and its substitution declaration would, be

.. |Blur_Layer_Size| replace:: :ref:`layer_blur Size`

and layer_blur Size would be added before the Size section in layer_blur.rst:

.. layer_blur Size

Size
~~~~

I think the above task can be done automatically with Python scripts. If there are any suggestions or easier ways to do this, please tell me.

If you are good at regex (I am not) you can please give me expression to easily find them (anything from above) in the document. I will start working on it tomorrow.

1 Like

I have written a script in Python which will go through all the files and collect the links and create the substitution for them.
So

`Linking <Linking>`__

will map to

|Linking|

(Currently everything is saved in another file called maps.txt, the original files are not modified)
I think my next step would be to create all the label that are not present for section in a group. And then collect them in a file and then map them according to the substitutions that are generated now.
main.zip (552 Bytes)
(Suggest any improvements. my next step is to find an replace with the substitution with single command)

3 Likes

main.zip (829 Bytes)

Now the script updates the content, saves the labels in labels.txt and substitution in maps.txt, now the last task is to manually add the labels to the substitution (some fix). Synfig documentation redirects - Google Docs will be helpful, but it doesn’t have all the labels.

New labels that are generated using the script are not available also. I will do some more testing and then we can finally complete the substitutions in maps.txt.

There are 269 substitution which we manually need to map to labels. I will soon create some way so that anyone can contribute for this (something like a public editable Google Docs or something else)

While making HTML form Sphinx, error are thrown for undefined substitutions only I and some malformed links. As there are not much malformatted links errors thrown we can fix that later.

If you have any doubt you ask me, also any suggestion.

1 Like

@veermetri05 as you think about all the suggestions given, I would also suggest that some where, the documentation needs more hands on examples to give a new user skills. My personal experience is that when I started synfig, I also found myself relying on other sources of info like YT videos because I considered the documentation difficult with few basic user friendly examples.

1 Like

@KonstantinDmitriev I was just trying to fix the URLs on the Getting Started — Synfig User Manual 1.4.0 documentation (read the docs) as I started to go through the links one by one and fixing them I found out that there are links that don’t exist. Even the empty pages are not created for them. And also there is nothing on the old wiki. For example on Getting Started - Synfig Animation Studio (wiki) there is link for root canvas which doesn’t even exist on old wiki.
https://wiki.synfig.org/index.php?title=Root_Canvas&action=edit&redlink=1 (root canvas).

I just want to know should I create empty pages for them ? or just convert them to simple text.

1 Like