[iTowns-dev] Tutorials

Fri Jun 30 02:52:02 PDT 2017

> I can start to work on the website and make a PR when I have the first pass
> ready, WDYT?

Super glad of it :)

> I really like the three.js/docs layout.
> On the same page you get access to: tutorials/introduction articles, API
> documentation and examples.

Yes this way is quite powerful I really like it too!

>  I believe that, as iTowns' users will also be three.js users,  it makes sense to try to match the style and
> organization of three.js website.
> I guess that all the discussed tools have configurable layout/template, so it shouldn't be too hard to achieve.

Yes, it is a major point that we are using THREEJS so the vast majority of 3D web coders could use itowns easily so some nice reference of it are always good.
Nevertheless iTowns target the geospatial world so we should find a nice mix that suit 3d freaks and people coming for effortless light web mapping

--
Alexandre Devaux
Chargé d'Etudes et de Recherche
Laboratoire MATIS, IGN
Tel: 01 43 98 85 73

________________________________________
De : iTowns-dev [itowns-dev-bounces at lists.osgeo.org] de la part de itowns-dev-request at lists.osgeo.org [itowns-dev-request at lists.osgeo.org]
Date d'envoi : vendredi 30 juin 2017 10:11
À : itowns-dev at lists.osgeo.org
Objet : iTowns-dev Digest, Vol 13, Issue 8

Send iTowns-dev mailing list submissions to
        itowns-dev at lists.osgeo.org

To subscribe or unsubscribe via the World Wide Web, visit
        https://lists.osgeo.org/mailman/listinfo/itowns-dev
or, via email, send a message with subject or body 'help' to
        itowns-dev-request at lists.osgeo.org

You can reach the person managing the list at
        itowns-dev-owner at lists.osgeo.org

When replying, please edit your Subject line so it is more specific
than "Re: Contents of iTowns-dev digest..."

Today's Topics:

   1. Re: Tutorials (Pierre-Eric Pelloux-Prayer)
   2. Re: Tutorials (Augustin Trancart)

----------------------------------------------------------------------

Message: 1
Date: Fri, 30 Jun 2017 09:11:13 +0200
From: Pierre-Eric Pelloux-Prayer
        <pierre-eric.pelloux-prayer at oslandia.com>
To: itowns-dev at lists.osgeo.org
Subject: Re: [iTowns-dev] Tutorials
Message-ID: <2d508fd4-0311-cbb4-0d06-faddf7cf29e3 at oslandia.com>
Content-Type: text/plain; charset=utf-8

Hi,

>
> Victor and I wrote a draft for tutorials (some of it is obsolete), in the readme here:
> https://github.com/iTowns/itowns2/tree/README

Good idea, and thanks for working on the documentation topic.

>
> I think ideally we should have a tutorials page which list all tutorials which will have their own page.
>
> Something like:
> itowns-project.org/tutorials.html
>   itowns-project.org/tutorials/basicstartup.html
>   itowns-project.org/tutorials/addGeometryTutorial.html
>   ...
>

I really like the three.js/docs layout.
On the same page you get access to: tutorials/introduction articles, API documentation and examples.

One big + is that you can just type something in the search bar (eg: Material) and you get to discover
everything available on the subject.

> If you have other ideas on that topic don't hesitate!

Here are 3 independant ideas:

1. for examples/tutorials, I think litterate programming offers a nice solution.

A big part of https://github.com/iTowns/itowns2/blob/README/README.md is a copy paste of index.html.
I see at least 2 benefits to write the same content direclty in index.html:
  - index.html would become documented :)
  - the comments would be easier to keep synchronized with itowns changes (it's too easy to forget to
    update the README.md or addGeometry.md)

2. consistent documentation style for examples and API

See issue https://github.com/iTowns/itowns2/issues/314 (discussing jsdoc, docco and other tools for API doc)

Also it could make sense to use a single tool to build our website (instead of jekyll + API doc tool + examples/tutorial
doc tool).
Here's what I imagined: docco for API/examples doc and a static landing page showing the README.md + screenshots of
itowns app (like https://threejs.org/).

3. I believe that, as iTowns' users will also be three.js users,  it makes sense to try to match the style and
organization of three.js website.
I guess that all the discussed tools have configurable layout/template, so it shouldn't be too hard to achieve.

Regards,
Pierre-Eric

------------------------------

Message: 2
Date: Fri, 30 Jun 2017 10:11:48 +0200
From: Augustin Trancart <augustin.trancart at oslandia.com>
To: itowns-dev at lists.osgeo.org
Subject: Re: [iTowns-dev] Tutorials
Message-ID: <182e60f8-5e58-b633-a45d-bf93e9dd7b33 at oslandia.com>
Content-Type: text/plain; charset="utf-8"

Hi !

Great for the README, I'll try to comment on it today.

On 29/06/2017 19:29, Alexandre Devaux wrote:
> Hi folks,
>
> Victor and I wrote a draft for tutorials (some of it is obsolete), in the readme here:
> https://github.com/iTowns/itowns2/tree/README
>
> I think ideally we should have a tutorials page which list all tutorials which will have their own page.
>
> Something like:
> itowns-project.org/tutorials.html
>   itowns-project.org/tutorials/basicstartup.html
>   itowns-project.org/tutorials/addGeometryTutorial.html
>   ...

Yep, but AFAIK we don't have tutorials yet, right? As the release is next week,
we might not have time to write those. Let's add a tutorial section when the
first one is written.

>
> Currently the website is on https://github.com/iTowns/itowns.github.io, we could store images of examples there.

Let's be more ambitious and store real, working examples in the landing page!
After all itowns is web-based, images are so 1990 ;-) One implication of this:
we should detect if the user is on an unsupported browser, and either display a
warning or display a screenshot instead (or both)? Or we don't care, considering
that most of our visitors would be from supported browsers?

I can start to work on the website and make a PR when I have the first pass
ready, WDYT?

>
> If you have other ideas on that topic don't hesitate!
>
> Feel free to contribute on https://github.com/iTowns/itowns2/tree/README

Thanks!

>
> Alexandre

I carry on:

On 30/06/2017 09:11, Pierre-Eric Pelloux-Prayer wrote:
>>
>> I think ideally we should have a tutorials page which list all tutorials
which will have their own page.
>>
>> Something like:
>> itowns-project.org/tutorials.html
>>   itowns-project.org/tutorials/basicstartup.html
>>   itowns-project.org/tutorials/addGeometryTutorial.html
>>   ...
>>
>
> I really like the three.js/docs layout.
> On the same page you get access to: tutorials/introduction articles, API
documentation and examples.

Agreed.

>
> One big + is that you can just type something in the search bar (eg: Material)
and you get to discover
> everything available on the subject.

We *need* that. I'll work on this.

>
>> If you have other ideas on that topic don't hesitate!
>
> Here are 3 independant ideas:
>
> 1. for examples/tutorials, I think litterate programming offers a nice solution.

That's clearly a big plus on docco for the examples.

>
> 2. consistent documentation style for examples and API
>
> See issue https://github.com/iTowns/itowns2/issues/314 (discussing jsdoc,
docco and other tools for API doc)
>
> Also it could make sense to use a single tool to build our website (instead of
jekyll + API doc tool + examples/tutorial
> doc tool).

Not necessarily... I don't know: it might cause more pain that it solves. It
depends what we want in the website (do we want individual pages that are
neither api doc nor examples?)

>
>
> Regards,
> Pierre-Eric

Same ;-)

Augustin Trancart - Oslandia

>
> ________________________________________
> De : iTowns-dev [itowns-dev-bounces at lists.osgeo.org] de la part de itowns-dev-request at lists.osgeo.org [itowns-dev-request at lists.osgeo.org]
> Date d'envoi : jeudi 29 juin 2017 15:20
> À : itowns-dev at lists.osgeo.org
> Objet : iTowns-dev Digest, Vol 13, Issue 6
>
> Send iTowns-dev mailing list submissions to
>         itowns-dev at lists.osgeo.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         https://lists.osgeo.org/mailman/listinfo/itowns-dev
> or, via email, send a message with subject or body 'help' to
>         itowns-dev-request at lists.osgeo.org
>
> You can reach the person managing the list at
>         itowns-dev-owner at lists.osgeo.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of iTowns-dev digest..."
>
>
> Today's Topics:
>
>    1. Re: Video in repo (Thomas Broyer)
>    2.  Release: name and version? (Alexandre Devaux)
>    3. Re: Release: name and version? (Augustin Trancart)
>
>