[jira] [Comment Edited] (ARIA-309) ARIATOSCA developer website improvements

["Miguel Jiménez (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/ARIA-309?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16342992#comment-16342992 ] 

Miguel Jiménez edited comment on ARIA-309 at 1/29/18 7:20 AM:
--------------------------------------------------------------

Hi,

In [^TOSCA-dev-website.pdf] I have pointed out some issues with the current distribution of information between the two TOSCA repositories (source code and website). I'm not sure this count as website improvement, but you can definitely see that there's some info overlapping that can potentially hinder maintaining the website. For instance, after each release, the website has to be updated to ensure that the latest docs are generated; as an example, the current generated docs are for TOSCA 0.1.1.

We could discuss during the next grooming meeting about where to put (1), (2), (3), and (4) (cf. the PDF file).

*EDIT*: Also, the files are in different format: markdown and reStructuredText. Should we unify the format?


was (Author: jachinte):
Hi,

In [^TOSCA-dev-website.pdf] I have pointed out some issues with the current distribution of information between the two TOSCA repositories (source code and website). I'm not sure this count as website improvement, but you can definitely see that there's some info overlapping that can potentially hinder maintaining the website. For instance, after each release, the website has to be updated to ensure that the latest docs are generated; as an example, the current generated docs are for TOSCA 0.1.1.

We could discuss during the next grooming meeting about where to put (1), (2), (3), and (4) (cf. the PDF file).

> ARIATOSCA developer website improvements
> ----------------------------------------
>
>                 Key: ARIA-309
>                 URL: https://issues.apache.org/jira/browse/ARIA-309
>             Project: AriaTosca
>          Issue Type: Task
>            Reporter: Ran Ziv
>            Assignee: Thomas Nadeau
>            Priority: Major
>         Attachments: TOSCA-dev-website.pdf
>
>
> Notes for rebooting the Aria-Tosca Getting Started 
> Guide
> This document includes things needed to reboot the existing Getting Started guide from http://ariatosca.incubator.apache.org/getting-started/ and https://github.com/apache/incubator-ariatosca/blob/master/README.rst  The goal here is to have a newbie be able to get up to speed and run a basic example in 30 minutes or less. 
> Make http://ariatosca.incubator.apache.org/getting-started/ point at the live Github
> Do we need to handle different releases?
> I don’t think so. As long as we’re before release 1.0, we should only have to target the latest.
> Create a matrix for releases + examples that work together
> Note in the README to find versions (including latest)
> Pointer to here: https://dist.apache.org/repos/dist/dev/incubator/ariatosca/
> Email thread with example steps taken by Vish to install latest  (.1.1) on Ubuntu 16
> There should be a note in the Getting Started page mentioning that the steps are generic for the different releases. Have a link that lists out concrete steps for Ubuntu 16.04, CentOS and other supported OS. These links would illustrate how to get the different release artifacts(e.g git checkout tags/0.1.1) for the different OS.
> + Windows and Mac OS
> Ran mentioned about the workaround of using “--no-binary” as part of “sudo pip install apache-ariatosca[ssh] --no-binary apache-ariatosca” in order to be able to successfully create aria services. Is there a JIRA that tracks fixing this work around?
> Add -H to PIP commands (for certain situations)
> I think what we generally need to do is show two kinds of install: general for the OS (in which case you need -H) and in a virtual environment (in which case you don’t).
> Have a note pointing to the Github README.md (https://github.com/apache/incubator-ariatosca/blob/master/README.rst)
>  
> Amend the “Getting Started” section at the bottom of the README to include examples from different versions and platforms in combinations that work out of the box.
> It would be nice to have 
> live running demo env (like ONOS)
> a simple/straight-forward link to images and examples such as this:
> http://onosproject.org/software/
> https://wiki.onosproject.org/display/ONOS/Tutorials
> Quick start with a VM or Container like this (https://wiki.onosproject.org/display/ONOS/Basic+ONOS+Tutorial)
> Updated/complete Docker images stored on Docker Hub and instructions for how to run.
> https://hub.docker.com/r/apacheariatosca/aria/
> Update instructions for running including for releases 
> Create different containers per major examples?
> Might have to 
> FYI Below were the set of steps that got me an end to end successful run on ubuntu 16.04 and is captured at http://mail-archives.apache.org/mod_mbox/incubator-ariatosca-dev/201708.mbox/%3cMWHPR2201MB1309A05B49D5F8415ED4D683A49C0@MWHPR2201MB1309.namprd22.prod.outlook.com%3e
> sudo apt-get update
> sudo apt install -y python-pip git
> sudo pip install --upgrade pip setuptools
> sudo apt-get install -y python-dev gcc libffi-dev libssl-dev
> sudo pip install apache-ariatosca[ssh] --no-binary apache-ariatosca
> git clone https://github.com/apache/incubator-ariatosca.git
> cd incubator-ariatosca
> git checkout tags/0.1.1
> aria service-templates store examples/hello-world/helloworld.yaml my-service-template
> aria services create my-service -t my-service-template
> aria executions start install -s my-service
> Example Dockerfile for aria on ubuntu 16.04 ( For those familiar with Docker) #TODO: Need to push to dockerhub and provide additional instructions (
> pulling the image - docker pull apacheariatosca/aria
> and running the container - docker run -it apacheariatosca/aria bash
> ) for running the container.
> FROM ubuntu:16.04
> RUN apt-get update && apt-get install -y \
>     python-dev \
>     gcc \
>     libffi-dev \
>     libssl-dev \
>     python-pip \
>     git \
>     wget
> RUN pip install --upgrade pip setuptools
> RUN pip install apache-ariatosca[ssh] --no-binary apache-ariatosca
> WORKDIR /tmp
> RUN git clone https://github.com/apache/incubator-ariatosca.git /tmp/incubator-ariatosca
> WORKDIR /tmp/incubator-ariatosca
> RUN git checkout tags/0.1.1
> These are artifacts from when this issue was previously created; make sure they are satisfied.
> 1) Create a {{Downloads}} section/page, with links to the canonical Apache release.
> 2) Add links to relevant resources and tools (Github repository, Confluence, contribution guide, etc.).
> 3) Add the releases' auto-generated API docs.
> 4) Add links to the TOSCA theoretical overview by [~emblemparade].



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)