Re: AW: AW: [FlexJS] Starting with the Docs

[Nemi]

About comments option, of course it is more work, but just saying, IMHO it
will give very easy way for community to add code use examples, snippets
related to topic, report error in docs, suggest docs improvement, ask
question.. etc 
Hm maybe something like PHP has "User Contributed Notes".



--
View this message in context: 
http://apache-flex-development.247.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005p55261.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.

AW: AW: AW: AW: AW: [FlexJS] Starting with the Docs

[Christofer Dutz]

I'll ask the Infra guys on Hipchat about this ... probably the times when I 
noticed my changes "going online" was when one of you guys released his changed 
from the staging site and then my stuff came with it.


Chris


Von: Alex Harui <aha...@adobe.com>
Gesendet: Dienstag, 13. September 2016 22:57:11
An: dev@flex.apache.org
Betreff: Re: AW: AW: AW: AW: [FlexJS] Starting with the Docs



On 9/13/16, 1:48 PM, "Christofer Dutz" <christofer.d...@c-ware.de> wrote:


>Could someone please explain how these Website SCMs play together? I
>noticed recently that I updated the installer.xml, but my changes didn't
>directly find their way into the website, but now it's online. So there
>must be some mechanisms in play here.
>

AIUI, Flex is using The ASF CMS known as SVNPubSub.  Our SVN repo at
https://svn.apache.org/repos/asf/flex/site/trunk
is watched for changes by a robot which builds a staging site, then on
approval, publishes to some other SVN copy that is served as flex.a.o.  A
commit to flex/site/trunk doesn't go public until you use the CMS to push
it to production.  Really painful, IMO, but good for major work since you
can see it staged first.  I wouldn't have any objection to changing, or
leveraging GitHub more.

I believe some projects have opted out of SVNPubSub and use different
processes to publish their sites.

-Alex

Re: AW: AW: AW: AW: [FlexJS] Starting with the Docs

[Alex Harui]

On 9/13/16, 1:48 PM, "Christofer Dutz"  wrote:


>Could someone please explain how these Website SCMs play together? I
>noticed recently that I updated the installer.xml, but my changes didn't
>directly find their way into the website, but now it's online. So there
>must be some mechanisms in play here.
>

AIUI, Flex is using The ASF CMS known as SVNPubSub.  Our SVN repo at
https://svn.apache.org/repos/asf/flex/site/trunk
is watched for changes by a robot which builds a staging site, then on
approval, publishes to some other SVN copy that is served as flex.a.o.  A
commit to flex/site/trunk doesn't go public until you use the CMS to push
it to production.  Really painful, IMO, but good for major work since you
can see it staged first.  I wouldn't have any objection to changing, or
leveraging GitHub more.

I believe some projects have opted out of SVNPubSub and use different
processes to publish their sites.

-Alex

AW: AW: AW: AW: [FlexJS] Starting with the Docs

[Christofer Dutz]

Hi,


ok ... as I never activated the deployment feature, I had to fix a little, but 
now it is probably working.

The only problem I am having is that I don't quite understand how the site 
works. I have a subversion repository which seems to contain the website 
content, but then this seems to be mirrored at:


https://svn.apache.org/repos/infra/websites/production/flex/content/


Which is where the maven guys publish their site.


Could someone please explain how these Website SCMs play together? I noticed 
recently that I updated the installer.xml, but my changes didn't directly find 
their way into the website, but now it's online. So there must be some 
mechanisms in play here.


Chris


Von: Christofer Dutz <christofer.d...@c-ware.de>
Gesendet: Dienstag, 13. September 2016 18:18:42
An: dev@flex.apache.org
Betreff: AW: AW: AW: AW: [FlexJS] Starting with the Docs

Well I just set it up to publish the content once. We can have a look at it 
then.

I generally set it up to


scm:svn:https://svn.apache.org/repos/infra/websites/production/flex/content/maven/flexjs/${website.path}

While website-path is always set to "latest-dev" during development and to the 
version of the release for a release. So for now it would probably be:


https://flex.apache.org/maven/flexjs/latest-dev


But we'll just have a look. Hope I don't have to setup anything magical for the 
Subversion commit.


Chris




Von: Alex Harui <aha...@adobe.com>
Gesendet: Dienstag, 13. September 2016 17:20:35
An: dev@flex.apache.org
Betreff: Re: AW: AW: AW: [FlexJS] Starting with the Docs



On 9/13/16, 12:07 AM, "Christofer Dutz" <christofer.d...@c-ware.de> wrote:

>Hi all,
>
>
>How about me turning on the site deployment feature (It's the identical
>setup to the one of the Maven project). It would automatically deploy a
>sub-directory of "https://flex.apache.org; ... I would suggest
>"https://flex.apache.org/flexjs;. We could have a look at what it
>produces and find a way to add a form-mailer.
>
>
>Would this be acceptable?

Seems worth doing so we can see how it will look.  I read a bit about
GitHub pages and it sounded interesting to me.  I wonder if GH Pages would
get us more visibility than flex.a.o.

GH Pages seems to leverage "orphan" branches so the doc can be in the same
repo, but in a different "view" or branch so activity there won't clutter
changes to code.  Whether we use GH Pages or not, we might want to
consider organizing the doc that way.  I'm not sure if ASF projects are
required to release written doc that is effectively a web site.  We don't
have "releases" of our web site sources.

Gh Pages seems to support AsciiDoc.  I read a bit about AsciiDoc and
didn't easily get why it would be better than markdown.  It just seemed
like another flavor of markdown.

-Alex

AW: AW: AW: AW: [FlexJS] Starting with the Docs

[Christofer Dutz]

Well I just set it up to publish the content once. We can have a look at it 
then.

I generally set it up to


scm:svn:https://svn.apache.org/repos/infra/websites/production/flex/content/maven/flexjs/${website.path}

While website-path is always set to "latest-dev" during development and to the 
version of the release for a release. So for now it would probably be:


https://flex.apache.org/maven/flexjs/latest-dev


But we'll just have a look. Hope I don't have to setup anything magical for the 
Subversion commit.


Chris




Von: Alex Harui <aha...@adobe.com>
Gesendet: Dienstag, 13. September 2016 17:20:35
An: dev@flex.apache.org
Betreff: Re: AW: AW: AW: [FlexJS] Starting with the Docs



On 9/13/16, 12:07 AM, "Christofer Dutz" <christofer.d...@c-ware.de> wrote:

>Hi all,
>
>
>How about me turning on the site deployment feature (It's the identical
>setup to the one of the Maven project). It would automatically deploy a
>sub-directory of "https://flex.apache.org; ... I would suggest
>"https://flex.apache.org/flexjs;. We could have a look at what it
>produces and find a way to add a form-mailer.
>
>
>Would this be acceptable?

Seems worth doing so we can see how it will look.  I read a bit about
GitHub pages and it sounded interesting to me.  I wonder if GH Pages would
get us more visibility than flex.a.o.

GH Pages seems to leverage "orphan" branches so the doc can be in the same
repo, but in a different "view" or branch so activity there won't clutter
changes to code.  Whether we use GH Pages or not, we might want to
consider organizing the doc that way.  I'm not sure if ASF projects are
required to release written doc that is effectively a web site.  We don't
have "releases" of our web site sources.

Gh Pages seems to support AsciiDoc.  I read a bit about AsciiDoc and
didn't easily get why it would be better than markdown.  It just seemed
like another flavor of markdown.

-Alex

Re: AW: AW: AW: [FlexJS] Starting with the Docs

[Alex Harui]

On 9/13/16, 12:07 AM, "Christofer Dutz"  wrote:

>Hi all,
>
>
>How about me turning on the site deployment feature (It's the identical
>setup to the one of the Maven project). It would automatically deploy a
>sub-directory of "https://flex.apache.org; ... I would suggest
>"https://flex.apache.org/flexjs;. We could have a look at what it
>produces and find a way to add a form-mailer.
>
>
>Would this be acceptable?

Seems worth doing so we can see how it will look.  I read a bit about
GitHub pages and it sounded interesting to me.  I wonder if GH Pages would
get us more visibility than flex.a.o.

GH Pages seems to leverage "orphan" branches so the doc can be in the same
repo, but in a different "view" or branch so activity there won't clutter
changes to code.  Whether we use GH Pages or not, we might want to
consider organizing the doc that way.  I'm not sure if ASF projects are
required to release written doc that is effectively a web site.  We don't
have "releases" of our web site sources.

Gh Pages seems to support AsciiDoc.  I read a bit about AsciiDoc and
didn't easily get why it would be better than markdown.  It just seemed
like another flavor of markdown.

-Alex

Re: AW: AW: [FlexJS] Starting with the Docs

[Alex Harui]

Ideally, a comment tool would send an email to dev@.

This isn't the first time some expressed a "like" for doc comments.  I'm
not saying we have to have it, but it would be nice if it was possible for
some volunteer to make it happen.  Maybe our doc system will eventually be
a FlexJS app anyway.  It might need some really good filtering,
up-voting/down-voting for different variants of components, etc.

-Alex


On 9/11/16, 10:43 AM, "Christofer Dutz" <christofer.d...@c-ware.de> wrote:

>“Form mailer“. ... Stupid mobile Phone auto correction ;-(
>
>
>
>Von meinem Samsung Galaxy Smartphone gesendet.
>
>
> Ursprüngliche Nachricht 
>Von: Christofer Dutz <christofer.d...@c-ware.de>
>Datum: 11.09.16 19:33 (GMT+01:00)
>An: dev@flex.apache.org
>Betreff: AW: AW: [FlexJS] Starting with the Docs
>
>Well I think most projects don't have comment on features in their
>documentation sites. So fire me this wouldn't be a killer criteria.
>Especially because it would require us to monitor these comments too.
>It's getting more and more places we should monitor for questions, so I
>would prefer people having problems with the documentation to post on our
>lists. Eventually embedding a firm maker on the documentation would be an
>option.
>
>Chris
>
>
>
>Von meinem Samsung Galaxy Smartphone gesendet.
>
>
> Ursprüngliche Nachricht --------
>Von: Alex Harui <aha...@adobe.com>
>Datum: 11.09.16 07:16 (GMT+01:00)
>An: dev@flex.apache.org
>Betreff: Re: AW: [FlexJS] Starting with the Docs
>
>
>
>On 9/10/16, 2:36 AM, "Christofer Dutz" <christofer.d...@c-ware.de> wrote:
>
>>Hi Alex,
>>
>>
>>actually that's not quite true. We have the Wiki and the Website. The
>>problem is that usually changing the website is far more work than to
>>edit the wiki. The thing with the Maven Site generation however is that
>>it automatically generates the entire Project documentation AND
>>automatically updates the content in Subversion. All is prepared to start
>>doing this, but I disabled the final upload of the generated site as we
>>haven't discussed that yet and I didn't want to do it without. Even if
>>linking to ASDoc on the Flex Buildserver works, the server isn't really
>>great from a performance point of view. Having the documentation on the
>>main Apache Webservers would definitely be nicer.
>>
>>
>>Have you guys had a look at the links I provided? The cool thing with
>>them is that they are absolutely standard and anyone will know where to
>>look for what information. Every maven-based projects has the same.
>
>I haven't looked closely myself because I don't have any objection to
>using something different.  I'm slowly trying to build consensus to build
>on not just what "technology" to use, but also how to use it.  I'm not
>sure how to get comments on the website pages, so I'd be tempted to host
>FlexJS doc elsewhere, like in a new repo for Tour de FlexJS.  Looks like
>there are comment plugins for GH pages.   The wiki is just what we have
>for now.  I don't expect we'll use it forever.
>
>-Alex
>

Re: AW: AW: [FlexJS] Starting with the Docs

[OmPrakash Muppirala]

On Sep 11, 2016 10:44 AM, "Christofer Dutz" <christofer.d...@c-ware.de>
wrote:
>
> “Form mailer“. ... Stupid mobile Phone auto correction ;-(

Haha, I just read it and was about to google for 'firm maker for docs' :-D

>
>
>
> Von meinem Samsung Galaxy Smartphone gesendet.
>
>
>  Ursprüngliche Nachricht 
> Von: Christofer Dutz <christofer.d...@c-ware.de>
> Datum: 11.09.16 19:33 (GMT+01:00)
> An: dev@flex.apache.org
> Betreff: AW: AW: [FlexJS] Starting with the Docs
>
> Well I think most projects don't have comment on features in their
documentation sites. So fire me this wouldn't be a killer criteria.
Especially because it would require us to monitor these comments too. It's
getting more and more places we should monitor for questions, so I would
prefer people having problems with the documentation to post on our lists.
Eventually embedding a firm maker on the documentation would be an option.
>
> Chris
>
>
>
> Von meinem Samsung Galaxy Smartphone gesendet.
>
>
>  Ursprüngliche Nachricht 
> Von: Alex Harui <aha...@adobe.com>
> Datum: 11.09.16 07:16 (GMT+01:00)
> An: dev@flex.apache.org
> Betreff: Re: AW: [FlexJS] Starting with the Docs
>
>
>
> On 9/10/16, 2:36 AM, "Christofer Dutz" <christofer.d...@c-ware.de> wrote:
>
> >Hi Alex,
> >
> >
> >actually that's not quite true. We have the Wiki and the Website. The
> >problem is that usually changing the website is far more work than to
> >edit the wiki. The thing with the Maven Site generation however is that
> >it automatically generates the entire Project documentation AND
> >automatically updates the content in Subversion. All is prepared to start
> >doing this, but I disabled the final upload of the generated site as we
> >haven't discussed that yet and I didn't want to do it without. Even if
> >linking to ASDoc on the Flex Buildserver works, the server isn't really
> >great from a performance point of view. Having the documentation on the
> >main Apache Webservers would definitely be nicer.
> >
> >
> >Have you guys had a look at the links I provided? The cool thing with
> >them is that they are absolutely standard and anyone will know where to
> >look for what information. Every maven-based projects has the same.
>
> I haven't looked closely myself because I don't have any objection to
> using something different.  I'm slowly trying to build consensus to build
> on not just what "technology" to use, but also how to use it.  I'm not
> sure how to get comments on the website pages, so I'd be tempted to host
> FlexJS doc elsewhere, like in a new repo for Tour de FlexJS.  Looks like
> there are comment plugins for GH pages.   The wiki is just what we have
> for now.  I don't expect we'll use it forever.
>
> -Alex
>

AW: AW: [FlexJS] Starting with the Docs

[Christofer Dutz]

“Form mailer“. ... Stupid mobile Phone auto correction ;-(



Von meinem Samsung Galaxy Smartphone gesendet.


 Ursprüngliche Nachricht 
Von: Christofer Dutz <christofer.d...@c-ware.de>
Datum: 11.09.16 19:33 (GMT+01:00)
An: dev@flex.apache.org
Betreff: AW: AW: [FlexJS] Starting with the Docs

Well I think most projects don't have comment on features in their 
documentation sites. So fire me this wouldn't be a killer criteria. Especially 
because it would require us to monitor these comments too. It's getting more 
and more places we should monitor for questions, so I would prefer people 
having problems with the documentation to post on our lists. Eventually 
embedding a firm maker on the documentation would be an option.

Chris



Von meinem Samsung Galaxy Smartphone gesendet.


 Ursprüngliche Nachricht 
Von: Alex Harui <aha...@adobe.com>
Datum: 11.09.16 07:16 (GMT+01:00)
An: dev@flex.apache.org
Betreff: Re: AW: [FlexJS] Starting with the Docs



On 9/10/16, 2:36 AM, "Christofer Dutz" <christofer.d...@c-ware.de> wrote:

>Hi Alex,
>
>
>actually that's not quite true. We have the Wiki and the Website. The
>problem is that usually changing the website is far more work than to
>edit the wiki. The thing with the Maven Site generation however is that
>it automatically generates the entire Project documentation AND
>automatically updates the content in Subversion. All is prepared to start
>doing this, but I disabled the final upload of the generated site as we
>haven't discussed that yet and I didn't want to do it without. Even if
>linking to ASDoc on the Flex Buildserver works, the server isn't really
>great from a performance point of view. Having the documentation on the
>main Apache Webservers would definitely be nicer.
>
>
>Have you guys had a look at the links I provided? The cool thing with
>them is that they are absolutely standard and anyone will know where to
>look for what information. Every maven-based projects has the same.

I haven't looked closely myself because I don't have any objection to
using something different.  I'm slowly trying to build consensus to build
on not just what "technology" to use, but also how to use it.  I'm not
sure how to get comments on the website pages, so I'd be tempted to host
FlexJS doc elsewhere, like in a new repo for Tour de FlexJS.  Looks like
there are comment plugins for GH pages.   The wiki is just what we have
for now.  I don't expect we'll use it forever.

-Alex

AW: AW: [FlexJS] Starting with the Docs

[Christofer Dutz]

Hi Olaf,

Asdoc integration is on my to-do list. But for this we need to port/add the 
asdoc support to falcon. An alternative would be to use the old flex version, 
but we would need to publish the jar(s) to Maven central somehow.

Chris



Von meinem Samsung Galaxy Smartphone gesendet.


 Ursprüngliche Nachricht 
Von: OK <p...@olafkrueger.net>
Datum: 09.09.16 11:52 (GMT+01:00)
An: dev@flex.apache.org
Betreff: Re: AW: [FlexJS] Starting with the Docs

Christofer Dutz wrote
> You can also have a look at the output it creates at [1]

Looks very promising to me!

What would be the steps to achive a FlexJS component documentation using
this technique?
Probably we have to place one of these Asciidoc files for each relevant
strand and bead?
Would the component docs be part of the existing site build or inside its
own shell.
Would it be possible to include ASdocs with some magic?

Only to consider another option:
I just realize that the flex asdoc [1] are part of Apache.
Are there also tools available to build this also nice documentation?

Olaf

[1] https://flex.apache.org/asdoc/

Olaf



--
View this message in context: 
http://apache-flex-development.247.n4.nabble.com/FlexJS-Starting-with-the-Docs-tp55005p55016.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.