Move doc builder instructions into Docker (#125)

* Releasing 2.0.1 into master (#122)

* Clean up badges in README file (#116)

* improve badges

* cleanup

* wip

* wip

* wip

* Configuration Elements cannot be replaced (#117)

* Apply fixes from StyleCI

* Update composer.json

* Update release-drafter.yml

* Update release-drafter.yml

* Create bundler.yml

* Setting release dependencies

Co-authored-by: Romans Malinovskis <[email protected]>
Co-authored-by: Georg Marx <[email protected]>
Co-authored-by: Imants Horsts <[email protected]>
Co-authored-by: GitHub Web Flow <[email protected]>

* Add POC for "CRUD::addTo($app)" syntax

* Apply fixes from StyleCI

* Add unit tests

* Apply fixes from StyleCI

* remove this weird file

* Add dockerfile for easier doc preview

* Update instructions

* add doc integration instructions for PhpStorm

* Add mention of addTo() into the docs

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Georg Marx <[email protected]>
Co-authored-by: Imants Horsts <[email protected]>
Co-authored-by: GitHub Web Flow <[email protected]>

docs/Dockerfile

@@ -0,0 +1,17 @@
+FROM  python:2-stretch as builder
+
+WORKDIR /www
+
+ADD requirements.txt .
+
+RUN pip install  pip==9.0.1 wheel==0.29.0 \
+    && pip install -r requirements.txt
+
+ADD . .
+
+RUN make html
+#RUN cp -R images build/html/images
+
+FROM  nginx:latest
+
+COPY --from=builder /www/build/html /usr/share/nginx/html

docs/README.md

@@ -1,19 +1,9 @@
-How to build this documentation
+Our documentation can now be built in the Docker.
 
 ```
-sudo apt-get install python-sphinx python-setuptools
-sudo easy_install pip
-
-sudo pip install sphinx_rtd_theme
-sudo pip install sphinxcontrib-phpdomain
-
-make html
+docker build -t docs .
+docker run -p 8080:80 docs
 ```
 
-next open `html/index.html` in your browser
-
-```
-open html/index.html
-```
-
+Open http://localhost:8080/ in your browser.
 

docs/docs.rst

@@ -0,0 +1,43 @@
+================
+Writing ATK Docs
+================
+
+New users of Agile Toolkit rely on documentation. To make it easier for the
+maintainers to update documentation - each component of ATK framework comes
+with a nice documentation builder.
+
+Writing ATK Documentation
+=========================
+
+Open file "docs/index.rst" in your editor. Most editors will support
+"reSTructured Text" through add-on. The support is not perfect, but it works.
+
+If you are updating a feature - find a corresponding ".rst" file. Your editor
+may be able to show you a preview. Modify or extend documentation as needed.
+
+See also: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+
+Building and Testing Documentation
+==================================
+
+Make sure you have "Docker" installed, follow simple instructions in
+"docs/README.md".
+
+Integrating PhpStorm
+--------------------
+
+You can integrate PhpStorm build process like this:
+
+.. figure:: images/doc-build-phpstorm1.png
+   :scale: 50 %
+   :alt: Create build configuration for the Dockerfile
+
+
+.. figure:: images/doc-build-phpstorm2.png
+   :scale: 50 %
+   :alt: Adjust Port settings to expose 80 as 8080
+
+.. figure:: images/doc-build-phpstorm3.png
+   :scale: 50 %
+   :alt: Use "Ctrl+R" anytime to build docs
+

docs/factory.rst

@@ -16,14 +16,26 @@ things like:
 
 Thanks to Factory trait, the following code::
 
-   $view->add(['Button', 'A Label', 'icon'=>'book', 'action'=>My\Action::class]);
+   $button = $app->add(['Button', 'A Label', 'icon'=>'book', 'action'=>My\Action::class]);
 
 can replace this::
 
    $button = new \atk4\ui\Button('A Label');
    $button->icon = new \atk4\ui\Icon('book');
    $button->action = new My\Action();
+   $app->add($button);
 
+Type Hinting
+------------
+
+Agile Toolkit 2.1 introduces support for a new syntax. It is functionally
+identical to a short-hand code, but your IDE will properly set type for
+a `$button` to be `class Button` instead of `class View`::
+
+    $button = Button::addTo($view, ['A Label', 'icon'=>'book', 'action'=>My\Action::class]);
+
+The traditional `$view->add` will remain available, there are no plans to
+remove that syntax.
 
 Class Name Resolution
 =====================

docs/index.rst

@@ -20,7 +20,7 @@ Object Containers
 .. figure:: images/containers.png
    :scale: 50 %
 
-Within your application / framework you can quite often have requirement for
+Within your application or framework you can quite often have requirement for
 using containers:
 
  - Form containing fields
@@ -273,3 +273,4 @@ Others
 
     debug
     session
+    docs

docs/requirements.txt

@@ -1 +1,2 @@
 sphinxcontrib-phpdomain
+sphinx_rtd_theme