WIP: Proposal for meta documentation

[MBB232]

Proposal for description of how documentation files can be structured + template (based on existing documentation)
meta-art like numbers, arrows and fonts for documentation pictures can be saved to this directory,

[ferdnyc]

Bunch of comments, mostly fairly brief. Not complete yet, but I got about 2/3 of the way through.

[ferdnyc]

Suggested change

	The tool used by Openshot is Sphinx to create both the online HTML and the offline manual.
	The tool used by OpenShot is Sphinx to create both the online HTML and the offline manual.

Drawing a distinction between "the online HTML and the offline manual" is a bit dubious here, since they're exactly the same HTML. A copy of what is otherwise the "offline manual" gets uploaded to the openshot.org site after it's generated by the build servers. (So, certainly the sentence as-is isn't wrong... other than the capitalization.)

[ferdnyc]

...Where?

[ferdnyc]

Ah. Maybe remove the previous line, and jut make the TODO about adding Reddit info?

[ferdnyc]

I don't know that it's really worth belaboring all the details here.

Suggested change

	License
	-------
	We use the GPL-3 license (see above) for documentation, see the header.
	This is for simplicity because it is the same license as the project code.
	And because the documentation gets parsed in other tools before it reaches its final form.
	License
	-------
	Project documentation is licensed under the same license as the source code.
	Specifically, the GNU General Public License version 3 or higher (GPLv3+); see the document header.

[ferdnyc]

The 'question' tag is actually auto-applied to any issue opened using the Question template. (Which is one of the reporting options we've defined a template for. The others are Bug Report and Feature Request, which apply the 'bug' and 'enhancement' tags respectively.)
So, it's really not an indicator of any particular status, since it's chosen by the user.

We also don't have a FAQ tag — perhaps we should, but we currently don't.

[ferdnyc]

These are really all just one four-paragraph block, our standard header. (It serves as all of those things, but they shouldn't be considered separate things.)

[ferdnyc]

Again, nix all mentions of translation please. Especially since this one also isn't true, or at least doesn't matter. When Sphinx outputs translation files, it flows sentence-per-line blocks back together and exports the entire paragraph as a single translation string.

[ferdnyc]

Nope to all of this, too. It should probably go. 😞

[MBB232]

Drawing a distinction between "the online HTML and the offline manual" is a bit dubious here, since they're exactly the same HTML. A copy of what is otherwise the "offline manual" gets uploaded to the openshot.org site after it's generated by the build servers. (So, certainly the sentence as-is isn't wrong... other than the capitalization.)

Hey, that is on you, for explaining Sphinx too well. 😁

"Plus, WYSIWYG to some extent implies a particular layout, whereas docs can be generated from reST using a variety of styles and formats, so the same docs will look very different depending how it's processed."
If it could, I thought it would. So I presumed that the offline doc would be PDF. (And possibly Epub, Winhelp/CHM/MShelp2, RTF, Writer and whatnot versions could exist.)

If they do not exist, then that line can indeed be shortened.

Or in this reddit thread.
Ah. Maybe remove the previous line, and jut make the TODO about adding Reddit info?

**It's a proposal that I did not feel up to me to decide. **
**It also depends on if topics on Reddit can be sticky to the top, how often you expect changes to the Help be needed, and if you have someone to regularly check it. **
I thought it could be a low-level way for people to make small suggestions. But if it is on top it may get abused, and if it is not on top it will be unable to find.
Since the meta-documentation is on github, it is probably fair to asume that the readers have an account. But if there are other places that suggestions for the docs are made, they should be listed so you can check them to see if something needs to be added.

I don't know that it's really worth belaboring all the details here.

(Re license info) I agree that it could be phrased shorter, but I was intentionally going for completeness of the details.
In five years the docs may need another large overhaul and someone is bound to ask; 'why is this not under CC license?' (Like I did). And you may not be here to explain.

The 'question' tag is actually auto-applied to any issue opened using the Question

Every 'question' is a question, but not all questions are the same.
Questions that get asked a lot should be in the FAQ, even (especially) if the answere is no, the asker does not stay around or it is already in the docs.

Questions with a good/complex answer may (partially) be used to update the docs or be in the FAQ, even if they are also an enhancement or bug.

So yes, I am proposing the creation of a FAQ-tag and more rigorous use of the Doc-tag. (Every time a new feature is added, it should be documented or screenshots may need updating.)
For example, I am waiting for #3346 to make it into the dailys so the framenumber will be included in the new screenshots.
People updating Docs or FAQ may do so every few months or once a year. Being able to sort issues on tags is probably faster then using the 'new feature' list from updates or working through all closed enhancements.

Reddit also seems to support tags, though I have not figured out how yet. If you have a regular Reddit-watcher, (s)he may want to add tag too.

Again, nix all mentions of translation please.

Yes, you mentioned that at the end of the other topic, was leaving it in for completion. (And maybe someone has an alternative)
Disappointing that it won't work in Sphinx. However, shorter lines may remain relevant if you process the Rest source files in other translation programs. OTOH, translating entire paragraphs can have benefits as some languages prefer longer sentences.
So I propose to hide it, and leave it till a process for translation is decided upon.

[ferdnyc]

You can reply to individual comments directly, in context, BTW. Instead of combining them all together. It helps a lot, in keeping track of the various points raised; each of the individual conversations can be marked "Resolved" when that item has been dealt with.

[ferdnyc]

In addition to the comments on specific details that I left above, a couple of general questions/notes:

1. I notice that in this PR, AboutDoc is in the root of the project, rather than inside the doc/ directory. Any reason for that change? I'm not sure about adding another directory to the project root, inside the doc/ direcory seemed like the right place to me.
2. In fact if we wanted to, we could rename/repurpose this slightly into the first chapter of a broader overall "Contributors Handbook" or "Contributors Guidelines". Something that could potentially cover more than just the documentation (things like coding style, testing methodology, etc.) Then it could live at doc/Guidelines/ or doc/Handbook/ or something like that.
   1. (I'm mostly bringing this up because it would affect how various settings would need to be defined, in things like the sphinx config file or the Actions task to auto-generate the doc.)
3. As an alternative to ad-hoc comments in the documentation, Sphinx has a plugin that enables support for a more formal work-in-progress annotation via a todo directive. And it has a couple of nice advantages:
   1. Ther's an accompanying todolist directive that will insert a collected listing of all of the todos across the entire set of documentation, displaying each note along with a link back to its location in the original context.
   2. todo directives have configurable visibility — if they're configured non-visible, they act like any other comment and don't show up in the rendered output.
   3. But if they're configured visible when generating the docs, then each one will be visible as an admonition box. Which opens up the possibility of even using them for notes inside the User Guide content as well. We'd normally configure it so they're hidden, but it then gives us the option to generate "editorial versions" of the Guide with all of the todo notes visible and indexed via todolist.

To embed a todo, it's written just like any other directive:

.. todo::

    Some note that should normally be invisible, but can be made visible.

.. todo:: For short notes, the entire thing can be on one line.

(The directive doesn't have to be all-lowercase, though it's more typical. But any capitalization is technically legal.)

And then (after converting an existing TODO comment into a todo directive and enabling the plugin), when the docs are configured for visible todos you get this:

[MBB232]

I notice that in this PR, AboutDoc is in the root of the project, rather than inside the doc/ directory. Any reason for that change?

Github. It must have jumped back to the root again when creating the new branch or when I switched or something. It was intended to be a subdirectoy of docs, as then it would be easily found by people wanting to edit the docs.
Can the location be easily fixed during the merge, or does it need to be re-pulled again?

[ferdnyc]

Can the location be easily fixed during the merge, or does it need to be re-pulled again?

It's easy enough to fix, we can just add a commit to the PR that moves the directory. (Renames all of the files inside it, effectively.)

[ferdnyc]

@MBB232: You asked, elsewhere,

I noticed a 'commit suggestion' button under some of your comments. Is that to accept them into my request?
Should I click on that to add them for the ones I agree with?

Yeah, exactly. Any you want to incorporate into the PR, you can do that right from the suggestion.

In fact, when suggestions are related (particularly in the same file), you can use "Add to batch" to queue them up and apply them all as a single commit.

[MBB232]

test. Comment keeps disappearing
Ah, there it went. #2989

I left it for a while in case others wanted to comment too.

I merged most of the easy things you committed.
How do I make the other changes that you suggested and I agree with, by making changes in my own fork? Or would that overwrite this topic?

Should the copyright notice in the template be redone in the old format too? As the headers are hidden, they are not processed by Spinx so the single-line does not really matter.

Good that you caught the name of the template, I guess I have a bad case of CamelType writing 😁
I must have made the mistake when recreating the 'clean' version , because I tested it in the original.
Do you want Documentation_About rewritten without capitals too?

Because I recreated my fork, I can confirm that the action is send with the updated source too. It is not automatically activated.

[MBB232]

Added most other suggestions in new branch, not sure what would happen if I made the changes directly in my pull request branch. Although I saw that your commits were included in it now.
https://github.com/MBB232/openshot-qt/blob/MBB232-AboutDoc-patch-1/doc/AboutDoc/Documentation_About.rst

[jonoomph]

@MBB232 You can keep committing and pushing to this PR branch. It won't break anything. Worst case, it might mark some comments as no longer relevant, but it doesn't delete any history on this PR. Go for it!

At the bottom of all these comments, it always says something like Add more commits by pushing to the MBB232-AboutDoc branch on MBB232/openshot-qt. 😄

[ferdnyc]

Should the copyright notice in the template be redone in the old format too? As the headers are hidden, they are not processed by Spinx so the single-line does not really matter.

If it's going to serve as a template, then yeah. It should contain the header as we'd want it to be used in any new files, which would be an exact copy of the header from any of the existing files (possibly with the year(s) modified).

Added most other suggestions in new branch, not sure what would happen if I made the changes directly in my pull request branch.

You should definitely make the changes on your MBB232-AboutDoc branch, so they're incorporated into the "living" PR. And as you noticed, you'll also see changes committed from our end too, either automatically by GitHub (as it synchronizes with the target branch, develop) or manually, like the changes I just pushed to fix some sphinx configuration.

[ferdnyc]

@MBB232 I pushed in the lion's share of my CSS changes, as well as some documentation changes that make use of them... which I'm now realizing I probably shouldn't have, since you mentioned wanting to keep those separate. So I'll probably back those out.

(Edit: Backed out. They're over on my docs-new-content branch, instead.)

Do you have an in-progress branch for changes to the User Guide files? If you open a PR from it I can push the changes there, instead.

[github-actions]

Merge conflicts have been detected on this PR, please resolve.

[jonoomph]

We have made some major changes to our documentation recently, and I am closing this PR until conflicts and merges can be resolved.