TaskBuster
==========

Welcome to the TaskBuster Documentation

$ pip install sphinx

Successfully installed Jinja2-2.10 MarkupSafe-1.0 Pygments-2.2.0 alabaster-0.7.11 babel-2.6.0 certifi-2018.8.24 chardet-3.0.4 docutils-0.14 idna-2.7 imagesize-1.0.0 packaging-17.1 pyparsing-2.2.0 requests-2.19.1 six-1.11.0 snowballstemmer-1.2.1 sphinx-1.7.8 sphinxcontrib-websupport-1.1.0 urllib3-1.23

# 원문의 진행과 실습의 스핑크스 버전의 차이에 따라 docs 디렉터리를 구성하고 진행합니다.
$ mkdir docs
$ cd docs
$ sphinx-quickstart

Welcome to the Sphinx 1.7.8 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
# 별도의 소스 및 빌드 디렉터
> Separate source and build directories (y/n) [n]: n

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
# 템플릿 및 정적 디렉터리의 접두사
> Name prefix for templates and static dir [_]: _

The project name will occur in several places in the built documentation.
> Project name: TaskBuster
> Author name(s): Doky
> Project release []: 0.1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: en

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
# 소스 파일 접미사
> Source file suffix [.rst]: .rst

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
# 마스터 문서의 이름(접미어 제외)
> Name of your master document (without suffix) [index]: index

Sphinx can also add configuration for epub output:
# epub 빌더 사용 여부
> Do you want to use the epub builder (y/n) [n]: n
Indicate which of the following Sphinx extensions should be enabled:
# 자동으로 모듈에서 문서화 문자열을 삽입
> autodoc: automatically insert docstrings from modules (y/n) [n]: n
# doctest가 블록 코드 조각을 자동으로 테스트
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: n
# 다른 프로젝트의 스핑크스 문서 간의 링크
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: n
# 빌드에 표시하거나 숨길 수 있는 todo 리스트 작성
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: n> coverage: checks for documentation coverage (y/n) [n]: n
# PNG나 SVG 이미지로 렌더링된 math 포함
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: n
# MathJax에 의해 브라우저에서 렌더링된 math 포함
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n
# config 값을 기반으로한 조건 포함
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: n
# 문서화된 python 객체의 소스 코드에 대한 링크 포함
> viewcode: include links to the source code of documented Python objects (y/n) [n]: n
# 깃헙에 게시할 .nojekyll 파일 만들기
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: n

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: n

Creating file ./conf.py.
Creating file ./index.rst.
Creating file ./Makefile.

Finished: An initial directory structure has been created.

You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

docs
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
└── index.rst

$ make html

build succeeded.

The HTML pages are in _build/html.
# 버전에 따라 다르지만, 비슷한 문구를 확인해야 합니다.

$ open ./index.html

$ git add .
$ git status
$ git commit -m "Sphinx installed and configured"
$ git push origin master

Welcome to TaskBuster's documentation!
======================================

This is an awesome **Django Project Boilerplate**!!

With this code you can start a *complex* Django Project
very quickly, with just a few steps!

Some of the TaskBuster Django Project Boilerplate functionalities are:

- **different virtual environments** for developing, testing and production
- **Internationalization** and **localization** to support different languages
- Project structure
- **HTML5 Boilerplate**
- Template Inheritance
- Functional **tests**
- robots.txt and humans.txt configured

Moreover, you can learn how to create this boilerplate **step by step**
in the |taskbuster_tutorial|. There you can learn, step by step, how
TaskBuster has been done, and even do it yourself if you want to!!

.. |taskbuster_tutorial| raw:: html

    <a href="http://marinamele.com/taskbuster-django-tutorial"
    target="_blank">TaskBuster Django Tutorial</a>

To start using the Boilerplate, check out the :doc:`requirements`
and next the :doc:`quick_start`.

Contents
--------

.. toctree::
   :maxdepth: 2

   requirements
   quick_start


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

$ touch docs/{requirements.rst,quick_start.rst}

Requirements
============

The requirements necessary to use this Django Project Boilerplate are:

- **python3** and **pip3**
- **virtualenv and virtualenvwrapper**
- **Firefox** (to use Selenium's Webdriver in functional Tests)
- **GNU gettext** (to use Internationalization)

If you don't have the first two requirements, you may find this
post useful: |python_install|.

.. |python_install| raw:: html

    <a href="http://www.marinamele.com/2014/07/install-python3-on-mac-os-x-and-use-virtualenv-and-virtualenvwrapper.html" target="_blank">Install Python 3 on Mac OS X and use virtualenv and virtualenvwrapper</a>

You can download Firefox from the official web page: |firefox_web|.

.. |firefox_web| raw:: html

    <a href="https://www.mozilla.org" target="_blank">Firefox</a>

And if you don't have GNU gettext, check this |taskbuster_section|.

.. |taskbuster_section| raw:: html

    <a href="http://marinamele.com/taskbuster-django-tutorial/internationalization-localization-languages-time-zones" target="_blank">TaskBuster tutorial section</a>


**Ready!?** Continue to the :doc:`quick_start`!

Quick Start Guide
=================


Download TaskBuster Django Project Boilerplate
----------------------------------------------

First, you need to download the BoilerPlate from GitHub.


Secret Django Key
-----------------

This boilerplate has the **DJANGO_KEY** setting variable hidden.

You can generate your DJANGO_KEY |django_key|.

.. |django_key| raw:: html

    <a href="http://www.miniwebtool.com/django-secret-key-generator"
    target="_blank">here</a>


Project Name
------------

This project is named *TaskBuster*, so if you are using this
Boilerplate to create your own project, you'll have to change
the name in a few places:

 - *taskbuster_project* **folder** (your top project container)
 - *taskbuster_project/taskbuster* **folder** (your project name)
 - virtual environment names: **tb_dev** and **tb_test** (name them whatever you want)
 - in virtual environments **postactivate** files (see section below), you have to change **taskbuster.settings.development** for your **projectname.settings.development**. Same works for the testing environment.


Virtual environments and Settings Files
---------------------------------------

First, you must know your Python 3 path::

    $ which python3

which is something similar to /usr/local/bin/python3.

Next, create a Development virtual environment with Python 3 installed::

    $ mkvirtualenv --python=/usr/local/bin/python3 tb_dev

where you might need to change it with your python path.

Go to the virtual enviornment folder with::

    $ cd $VIRTUAL_ENV/bin

and edit the postactivate file.:

    $ vi postactivate

You must add the lines: ::

    export DJANGO_SETTINGS_MODULE="taskbuster.settings.development"
    export SECRET_KEY="your_secret_django_key"

with your project name and your own secret key.

Next, edit the **predeactivate** file and add the line::

    unset SECRET_KEY

Repeat the last steps for your testing environment::

    $ mkvirtualenv --python=/usr/local/bin/python3 tb_test
    $ cd $VIRTUAL_ENV/bin
    $ vi postactivate

where you have to add the lines::

    export DJANGO_SETTINGS_MODULE="taskbuster.settings.testing"
    export SECRET_KEY="your_secret_django_key"

and in the predeactivate file::

    unset SECRET_KEY

Next, install the packages in each environment::

    $ workon tb_dev
    $ pip install -r requirements/development.txt
    $ workon tb_test
    $ pip install -r requirements/testing.txt



Internationalization and Localization
-------------------------------------

Settings
********

The default language for this Project is **English**, and we use internatinalization to translate the text into Catalan.

If you want to change the translation language, or include a new one, you just need to modify the **LANGUAGES** variable in the file *settings/base.py*. The language codes that define each language can be found |codes_link|.

.. |codes_link| raw:: html

    <a href="http://msdn.microsoft.com/en-us/library/ms533052(v=vs.85).aspx" target="_blank">here</a>

For example, if you want to use German you should include::

    LANGUAGES = (
        ...
        'de', _("German"),
        ...
    )

You can also specify a dialect, like Luxembourg's German with::

    LANGUAGES = (
        ...
        'de-lu', _("Luxemburg's German"),
        ...
    )

Note: the name inside the translation function _("") is the language name in the default language (English).

More information on the |internationalization_post|.

.. |internationalization_post| raw:: html

    <a href="http://marinamele.com/taskbuster-django-tutorial/internationalization-localization-languages-time-zones" target="_blank">TaskBuster post</a>


Translation
***********

Go to the terminal, inside the taskbuster_project folder and create the files to translate with::

    $ python manage.py makemessages -l ca

change the language "ca" for your selected language.

Next, go to the locale folder of your language::

    $ cd taskbuster/locale/ca/LC_MESSAGES

where taskbuster is your project folder. You have to edit the file *django.po* and translate the strings. You can find more information about how to translate the strings |translation_strings_post|.

.. |translation_strings_post| raw:: html

    <a href="http://marinamele.com/taskbuster-django-tutorial/internationalization-localization-languages-time-zones#inter-translation" target="_blank">here</a>

Once the translation is done, compile your messages with::

    $ python manage.py compilemessages -l ca



Tests
*****

We need to update the languages in our Tests to make sure the translation works correclty. Open the file *functional_tests/test_all_users.py*:

- in **test_internationalization**, update your languages with the translation of title text, here "Welcome to TaskBuster!"
- in **test_localization**, update your languages.



Useful commands
---------------

A list of all the commands used to run this template::

    $ workon tb_dev
    $ workon tb_test

    $ python manage.py makemessages -l ca
    $ python manage.py compilemessages -l ca

$ make html

$ git add .
$ git status
$ git commit -m "Documentation ready"