Home Website Youtube GitHub

Which branch for writing documentation

mGear Development
#1

I was thinking of sitting down writing some user documentation for mGear, starting with some basic Getting Started stuff for riggers and animators, and was wondering which branch to use. I can see that the docs are in mgear_dist, but should I be using the master branch or the gh-pages branch?

1 Like
#2

Hello @ragnar

If you are doing some documentation you need to know certain things.

We use Sphinx https://www.sphinx-doc.org/en/master/ to generate mGears documentation. For now there is no branch which contains the Sphinx doc project so if you are doing any volunteering on this subject please Fork mgear_dist which contains the rst files used to generate the docs.

1 Like
#3

Hello @ragnar thanks for your help offer
The docs rst are inside master branch in this folder https://github.com/mgear-dev/mgear_dist/tree/master/docs

the branch https://github.com/mgear-dev/mgear_dist/tree/gh-pages is for the generated documentation using sphinx

Which kind of documentation do you have in mind?

and this is the link to it https://www.mgear-framework.com/mgear_dist/

1 Like
#4

I’m starting with a quick start guide for Shifter, covering how to install mGear, and how to rig and animate a biped using the template.
Next, I was thinking of tackling all the different Shifter components, and write reference documentation for each one.
Finally I was hoping to write documentation on how to write your own Shifter component, partially to familiarize myself with the mGear code base.

I’ve forked the repo over to my github user (ragtag), but I haven’t committed anything there yet. I guess I’ll send you guys push requests when I have each portion ready…if that works for you.

I have one question though. When I try to build the documentation (“make html”), it complains about missing sphinx.ext.changelog_links, but I’m a bit unsure which package I’m missing? I’m using python2.7 and pip on CentOS 7.6 to install what I need for Sphinx. Any ideas?

3 Likes
#5

I got it working. I found this thread which had the changelog_links.py extension file in it.

I put that in mgear_dist/docs/exts/changelog_links.py and edited docs/source/conf.py to point to it, and it works…but I’m not sure this is the correct changelog_links.py file I should be using…and it should probably eventually be included in the mgear_dist repo.

1 Like
#6

Hi @ragnar

Thank you very much for this. Your documentation proposal is very welcome. :slight_smile:

I have found your fork and mark it to watch the changes.

And yes ! the file is needed for the release log auto reference :stuck_out_tongue:
This is the original link to the gilhub thread https://github.com/mgear-dev/mgear_dist/issues/19

if you have any question making the guides, just ask here :slight_smile:

Cheers,
Miquel

1 Like
#7

I’ve committed a work in progress Quick Start and a start of a Shifter Component Reference page to my fork. Feel free to review it and give feedback. Things like am I using the right terminology for things, am I missing something that should be in there and so on. There is still some Sphinx issues I need to fix, such as a broken internal link, and the Quick Start not only being added to the sidebar when on the Overview page.

The whole corona virus epidemic has thrown a bit of a wrench in my plans for this, with closed offices and more, so progress will be a bit slower than I had originally hoped. Hopefully you’re all well and staying healthy.

2 Likes
#8

Thanks @ragnar I will check it today :slight_smile:

#9

Hello @ragnar
It is looking great. I didn’t read all careful, but overall it is great!
I just adding here the links, so other people can check the WIP :slight_smile:


Thanks for the great work in the docs!

1 Like