[Bf-docboard] Current Status and Next Steps

Thu Jan 15 17:47:32 CET 2015

Here's a draft of the OS X install docs. I'm also new to SVN and
RST/Sphinx,along with some of the people who have been posting lately... so
this does seem much more complicated than a wiki to me too. Nonetheless, I
was able to work out how to successfully do the install on OS X,
translating from the Windows link that Greg posted a day or two ago.

I guess someone might have to sub-edit this to get it properly formatted in
RST and uploaded online to the docs page, if you want to use it, as I don't
know how to do that myself. I tried to format it in RST, using the View
page source link from the Windows page as a template but am not sure how it
turned out. Probably needs some fine tuning, but should be quick for
someone accustomed to RST workflow. The main difficulty I’m having is not
knowing how to preview the RST as HTML, so I can see how the built HTML
would turn out.

I did notice that when trying to download the Blender documentation repo
that the HTTPS certificate had a validation error and that stopped the
download with an alert. I had to press t to temporarily authorize it to
continue.

Should the URL be switched to http:// versus https:// in the docs if that
would avoid the error (that might scare new people)?

I also wondered whether or not the pip command will work on a stock OS X
machine without Command Line Tools installed? I can't answer that because I
have already installed them on mine.

Also, I had 355 warnings (some of them marked SEVERE) while building the
HTML... not sure if that is normal or not either, maybe adding a similar
note as the earlier section about warnings being OK (even SEVERE ones)
would help. The built HTML docs did seem to work in my browser despite the
warnings, but I only looked at the contents.html page.

Here's what I wrote, hope it is useful (attached as RST/txt).

On Thu Jan 15 2015 at 8:07:03 AM marco ardito <ardito at apiform.to.it> wrote:

>  Il 15/01/2015 13:56, Greg Zaal ha scritto:
>
>
>    - The manual at blender.org/manual is now the official one to use -
>    all the Help/manual links inside blender itself point to it.
>
>
>    - blender.org/documentation (which is now out-dated) needs to redirect
>    to blender.org/manual/about
>
>
> this page also needs to link the new one, perhaps.
> http://www.blender.org/support/ => online manual
> and maybe http://www.blender.org/get-involved/ => documentation
>
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20150115/0fa1beef/attachment.htm 
-------------- next part --------------

***************************************************************
Installation Guide for Editing the Blender Manual on OS X
***************************************************************

This guide covers the following topics:

#. `About SVN`_
#. `Downloading the Repository`_
#. `Setting up the Build Environment`_
#. `Building the HTML Files`_

About SVN
=========

SVN is a tool that allows multiple contributors to work on a project like Blender documentation together. All versions of OS X come with a version of SVN that will work with the rest of the install process as listed below.

You can double check that SVN is working correctly by doing this:

- Choose Finder in the Dock and click on it. 
- Open a new Finder window, with Command-N (or by using the menus with your mouse: File, New Finder Window). 
- Type Terminal in the search bar in the top right corner. 
- Double click on the search result that is an Application called Terminal, and has an icon that is a black square with >: inside of it.

Once the Terminal program opens, type:
::  

svn

followed by Return. You should see something like the following as a result:
::

Type 'svn help' for usage.

Great, this means that your SVN is working and you are ready for the next step.

Downloading the Repository
==========================

Now we can download the most recent version of the Blender documentation. SVN keeps this in an online container, called a repository. To download the Blender documentation repository you���ll want to check it out from the online container, much like you check out a book from the library: 

- Type the following into Terminal:
::

svn checkout https://svn.blender.org/svnroot/bf-manual/trunk/blender_docs

followed by Return. 
- The repository will now be downloaded which may take a few minutes depending on your internet connection. 
- Hundreds of files will fly by on your screen, and at the end you will see something like this:
::

Checked out revision 53.

That means that you now have all of the source files for the Blender documentation on your local hard drive. 

Setting up the Build Environment
================================

You���ll use a command from the Python programming language next to set up the Blender documentation environment on your Mac. Like SVN, OS X comes with Python built in. 

Python uses a command called pip to manage software packages that need more than one program installed to support them. The following pip command will install all of the supporting requirements on your Mac that you���ll need to take part in the Blender documentation project. 

SVN installed the Blender documentation into a new folder on your Mac called blender_docs. So, to access it you'll need to change directories into the new folder. In Terminal, type:
::

cd blender_docs

followed by Return. Next we'll use pip to install the requirements for the project:
::

pip install -r requirements.txt

If all goes well, you should see the following message when it���s finished:
::

Successfully installed Jinja2 MarkupSafe Pygments Sphinx docutils sphinx-rtd-theme Cleaning up...

During the setup some warnings may be shown, but don���t worry about them. However if any errors occur, they may cause some problems.

Building the HTML Files
=======================

We are now ready to convert all those rst documention source files into the pretty HTML files that people can see on their web browsers!

Type the following command into Terminal:
::

sphinx-build -b html ./manual ./build/html

followed by Return. This is the command you will always use when building the docs. 

Building the docs means converting them from the rst source files into the HTML web broswer files that are formatted for people to see. The building process may take ten minutes or more the first time (or after any major changes), but the next time you build it should only take a few seconds.

Once the docs have been built, all the HTML files can be found on your Mac���s local hard drive. Try opening the contents.html file in your web browser to read the manual:

- Go back to Finder in the Dock and again open a new Finder window, with Command-N (or by using the menus with your mouse: File, New Finder Window). - Next type:
::

contents.html

in the search bar in the top right corner, and this time click on the small pop-up just below the input window that will say:
::

Name matches: contents.html. 
- There should only be one result for your search, but if there is more than one, double click on the one that has the most recent Date Last Opened, because this file should have only been created minutes ago when you built the docs with the sphinx-build command. 

- Double click on contents.html and it should open your web browser (likely Apple���s Safari, if you have not changed your default OS X settings to use any other web browser). 

Congratualtions! You have successfully installed everything you need to take part in the Blender documentaion project with your Mac.

Now that you are able to build the manual, please visit blender.org/documentation for more information such as the style guide and how to submit patches and gain commit access.