[Bf-docboard] my first impressions about the new documentation system
Campbell Barton
ideasman42 at gmail.com
Tue Sep 2 16:48:33 CEST 2014
Thanks for working on the docs, comments inline.
On Tue, Sep 2, 2014 at 11:59 PM, Gaia <gaia.clary at machinimatrix.org> wrote:
> So after a few days of working with the new documentation system
> i need a break. Here is my personal experience with it. And i am
> sure others will have completely different experiences. However...:
>
> 1.) Installing the documentation system was not really complicated
> in my case, but my computer was already setup with a lot of tools
> like cygwin python 2.7, git. So most of the environment was up and
> running. It took me a while to understand that i also need pip
> (although i forgot where it became important). But all worked.
>
> 2.) registering as documentor was easy. actually i only needed to add
> myself as subscriber here:
>
> https://developer.blender.org/tag/documentation/
>
> 3.) getting the documentation repository was easy as well.
> No surprises here. But i am also used to work with the
> blender git repository, so i already knew how to get this
> to work.
>
> 4.) I was able to build the documentation from my Cygwin shell just by
> calling make. It took about 15 minutes to "compile" the docs, but
> only on the first build. from then on it was building in about 15
> seconds. I know that when you do not have Cygwin, then make won't
> work. But there seems to be a bat file for building on windows.
>
> 5.) I tried to get comfortable with the RestructuredText syntax and i
> found it a bit weird to use. I stumbled a lot over writing wrong
> indentation, and missing or too many blank lines and oddities like
> that. well, i can imagine that one can eventually get used to this.
> At the end its a bit like programming the documents and you need to
> learn yet another programming language...
Yep, learning a new markup takes some effort, I think its harder now
because we don't have so many good examples in the repo to compare
against (although ``render`` chapter is becoming quite a good
example).
> 6.) I find the Sphinx documentation can be helpful for developers, but
> it took me always a lot of time to understand how exactly the
> syntax was for specific issues i had. Some of the descriptions i
> just could not understand. Probably because i do not know how the
> documentation system functions internally. Others may find the
> sphinx documentation is perfect to read.
It does work a bit different to Wiki in that you are not supposed to
directly influence layout so much, instead write what you mean - and
let the generator render it. In some cases however you still want some
control.
> 7.) When i look at the compiled html files from my local browser, then
> it is almost ok. Just that the nice icons from font awesome show up
> as broken characters instead. I believe that is because firefox
> does not install the fonts when they come from a different location
> as the files. Internet explorer displays the icons fine.
Quite sure this is an issue with the theme we use, looks like we hit
~3 BUGS in the Theme (not RST/Sphinx... so if this is a trend we could
switch to one of the default themes, I really don't want to be
struggling with new docs just because of the theme).
.. it does look **so** much nicer then the default though.
> 8.) My first push was a disaster. I forgot to pull before pushing and
> everything broke. But i was told to create my own branch before
> pushing, so the disaster was revertible. Actually troubled helped
> me to recover. Thanks for that !
Always update before editing, In future conflicts shouldn't be so bad
(there were some automated edits I made that touched many files)
> 9.) I tried to make my documents pretty and nicely readable. That was a
> challenge in multiple ways:
>
> a.) It took me a long time to understand the sphinx directives.
> b.) Sphinx allows to create tool tip boxes. But there seems to be a
> bug which moves the box title into the box text area, and sets
> the title to the box type ("Note", "Warning", "Error", ...)
Ugh, bug in the theme (or result of the theme, default looks ok)
> c.) I have organized my documents with images aligned to the right
> page border. Sphinx by default uses a one column scheme which
> works ok when you have just a few images. while it is not a big
> issue to get images right aligned in Sphinx, the results are
> somewhat odd at times:
>
> - when you narrow the page to simulate a cell phone display,
> then the text left to the image gets squeezed too much.
> Maybe that is just a theme issue.
> - there is no layout alignment clearing
> (in html it would be like: <div style="clear:both;"></div> )
> however i found it is possible to add that as "raw html"
> into sphinx. That is ugly but working.
Worth checking if this is theme related too.
> 10.) The hierarchy display is odd. as it can not be collapsed. Also i
> was working within the Modeling chapter which displays about 130
> entries in the left navigation bar with all hierarchy levels
> expanded, and with no indentation.
>
> So for now i use the browser search to find my way through the
> hierarchies.
Modeling needs to be re-arranged, the ``manual/modeling/index.rst``
has way too many files, See how we did this for ``manual/render``
*(freestyle for example)*.
> 11.) What i am missing most is instant feedback on my changes. i often
> add a few lines of text then i want to see how the layout looks.
> So i frequently rebuild the documentation which takes a few
> seconds each time.
Theres a few RST editors out there but I didnt find them that great
beyond headings, bullets... basic stuff.
WYSIWYG editing is nice, but as time goes on I don't especially miss it.
> 12.) I need to switch between 3 windows:
>
> - edit in a text editor
> - build in a command shell
> - inspect in the browser.
>
> But of course i can place 3 windows on my computer screen to make this
> convenient.
More advanced editors can be configured to run a build, though am used
to [terminal/editor/blender] .. so this isn't that different.
> 13.) open questions for me:
>
> a.) How would this system work for multiple Blender versions ?
We tag each version (like the code), upload the builds (also like code)
> b.) How would this system work for internationalisation ?
Most likely branches.
> c.) How would many documentors work on this system ?
> here especially: How can one know that a specific document
> is already locked by another documentor ?
You don't know, if there are conflicts someone will have to resolve,
in practice not sure its such a problem - same for Blender's code.
> d.) How will my changes be propagated to the final online
> documentation ? are we all supposed to work on personal
> branches ? Will these branches be setup on the remote master ?
We have https://www.blender.org/manual/ eventually it sould do daily
builds (or build on each commit).
> e.) What about search ? the built in search seems to be limited.
The search seemed fairly good to me, it works well for Python-API
reference at least.
> All in all it took me some time to get used to the new system. For now
> i found it a bit frustrating to use because there are so many small
> issues, each of them is just a bit annoying, but all together are
> a bit of a pain (for me).
I think you gave yourself a fairly challenging task to begin with -
Learn a new markup, and for the first task layout an image heavy page.
Its fine - and you managed it, but you could have started with some
much smaller tasks and not hit so many problems all-at-once.
Again, if we had a more finished examples I think it would have been
easier for you too.
> So i take a break and step back to other things for a few days until i
> recovered from my first impressions ;-/ then i give it a second try.
>
> i hope that helps
> cheers,
> gaia
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
--
- Campbell
More information about the Bf-docboard
mailing list