[Bf-docboard] Other projects wiki/sphinx migration

[Campbell Barton]

Hi Marco
gitbooks this seems like a very rough equivalent to what we already have.
Since moving between documentations systems is a _big_ task,
there would need to be significant advantages (or if Sphinx became
un-maintained).

While the ability to edit documents online is nice, this is also
possible with Sphinx and more a feature we miss in our current version
control (Subversion and Phabricator).
I've seen a project using Sphinx have an "Edit" button on each page
which links you to the Github page to edit and create a pull request.
I've mentioned this before but we're not prevented from having online
editing with Sphinx,
its just not well supported by the tools we're currently using.

Some other observations on gitbooks.

- Using git for documents with 100's of images is impractical over time.
  (where everyone would checkout all images for all versions of
Blender ever published).
.. of course this can be mitigated..
maybe branches for each Blender version, or store images externally
(git annex/lfs).
As far as I can tell this is still quite awkward.

- Their translation support seems to be just having entire copies of the manual.
  (where sphinx supports translation strings with gettext).

- There is also difference in projects technology choices,
  gitbooks is JavaScript/Web oriented (for tools and plugins),
  while Sphinx uses Python and allows extensions to be written in Python.
  Since Blender uses Python, our API docs use Sphinx -
  its nice to work with a technology we're familiar with.

On Fri, Feb 26, 2016 at 10:57 PM, marco ardito <ardito at apiform.to.it> wrote:
> Il 19/02/2016 19:10, Campbell Barton wrote:
>
> Recently I found this article about 2 other projects migrating from a
> Wiki to Sphinx [0] for very similar reasons to us.
>
> These are quite technical projects, and some of the pain-points we ran
> into (build times and having to write our own tools in some cases)
> aren't mentioned.
> Nevertheless, interesting to see how other projects handle this.
>
> [0]: https://opensource.com/business/16/1/scale-14x-interview-dru-lavigne
>
>
> Interesting read, thanks.
>
> btw, I follow other (unrelated) FOSS projects, and some of them have very
> good documentation systems, imho.
>
> One of this is Teiid, a Jboss  data virtualization system: until now, they
> used only Confluence/Jira, which is very good and has free licenses for FOSS
> projects, but may be it is not ideal to them, for some reason: recently they
> are moving docs, for newer releases, to other systems, but they chose
> gitbook instead
>
> see https://www.gitbook.com/book/teiid/documents/details or also
> https://teiid.gitbooks.io
> also https://www.gitbook.com/about
>
> which also has pdf, epub, mobi export... which is nice, and it could allow
> an easier contribution model, maybe (I'm just guessing)
>
> Could it be suitable and/or worth considering for Blender Docs?
>
> --
> Marco
>
>
> ------------------- [Ai sensi e per gli effetti della Legge sulla tutela
> della privacy (L. 196/2003), questa mail è destinata unicamente alle persone
> sopra indicate e le informazioni in essa contenute sono da considerarsi
> strettamente riservate. E' proibito leggere, copiare, usare o diffondere il
> contenuto della presente mail senza autorizzazione. Se avete ricevuto questo
> messaggio per errore, siete pregati di rispedire la stessa al mittente.
> Grazie]
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>



-- 
- Campbell