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.
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.
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.
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:
Transfer basic text contents, formatting and images. Hyperlinks remaining broken at this point.
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.
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,
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.
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)
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.
@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.
I’ve been dabbling in animating with Synfig, and I want better documentation for users. While the user manual is nice, there’s a lot more that would be useful to document.
A good starting point would be setting some rough simple standards for writing docs; for that purpose, I could just migrate the Writer’s Documentation in the old wiki, but I’m not sure where to place writer’s docs. I’ve thought about the base directory of https://github.com/synfig/synfig-docs but it’s a bit too hidden.
Any suggestions about where I should place migrated writer’s docs?
, I haven’t even yet fixed all the links 
.