Deploy do .Net Core WebAPI no Heroku

Normalmente desenvolvedores dotnet preferem fazer deploy no Windows Azure por conta da facilidade do uso da plataforma mas muitos acabam procurando opções mais baratas e ágeis do que a plataforma da MSFT.

Hoje vou mostrar como fazer deploy no Heroku, um serviço de hospedagem na nuvem um pouquinho bem diferente do nosso querido Azure.

Heroku é um serviço do tipo PaaS (Platform as a Service) altamente customizável por conta das “buildpacks” que são arquivos que apontam detalhes das necessidades de software a serem instalados na sua infraestrutura a fim de hospedar sua aplicação. No Heroku, assim como no Azure temos uma estrutura de instâncias que são chamadas de Dynos, você iria optar por aumentar a quantidade de Dynos de sua infraestrutura caso você desejasse maior escalabilidade e redundância, assim como no Azure.

Mas vamos lá.. “Less talk, more code!”
Vou deixar para falar do Heroku, seus preços, Dynos e etc em um post dedicado.

Instalando o Heroku

O Heroku, como quase tudo, possui um CLI e eu inicialmente recomendo que você acesse este link e baixe a versão do instalador ao invés de instalar via NPM.

Após a instalação vale a pena reiniciar seu PC para garantir o bom funcionamento deste CLI.

Criando repositório no Git

Fique à vontade para criar um repositório no Git o qual você irá armazenar seu projeto e posteriormente ligá-lo a sua aplicação no Heroku.

Iniciando sua solution

Você pode usar o .Net Core CLI ou Visual Studio. O importante será criar seu projeto e abrir o arquivo packages.json e alterar a versão para “1.0.0“. A versão “1.0.1” não irá funcionar.

A seguir, execute o seguinte comando do Nugget no Package Manager Console:

Install-Package Microsoft.Extensions.Configuration.CommandLine

Por fim, altere as linhas de código do método Main em Program.cs

	using System;
	using System.Collections.Generic;
	using System.IO;
	using System.Linq;
	using System.Threading.Tasks;
	using Microsoft.AspNetCore.Hosting;
	using Microsoft.AspNetCore.Builder;
	using Microsoft.Extensions.Configuration;
	namespace WebAPI
	{
	public class Program
	{
	public static void Main(string[] args)
	{
	var config = new ConfigurationBuilder().AddCommandLine(args).Build();
	var host = new WebHostBuilder()
	.UseKestrel()
	.UseContentRoot(Directory.GetCurrentDirectory())
	.UseConfiguration(config)
	.UseIISIntegration()
	.UseStartup<Startup>()
	.Build();
	host.Run();
	}
	}
	}

view raw

Program.cs

hosted with ❤ by GitHub

Assim que terminar, faça commit e push de suas alterações e vamos ao Heroku.

git commit -am "Setup for Heroku"
git push

Criando sua aplicação no Heroku

Você pode criar um aplicação na interface gráfica caso tenha algum temor com linhas de comando no Bash ou Cmd (espero que não tenha) ou usar o CLI para acelerar as coisas.

Execute o login, você terá que fazer isso uma só vez:

heroku login

Na sequencia crie uma nova aplicação:

heroku create nome-da-app

Lembra que eu te disse que os buildpacks são responsáveis por “configurar” sua instância no Heroku. É exatamente isso que faremos, mesmo sabendo que este buildpack não é oficial do Heroku. (Sim, existem usuários que criam buildpacks para que você possa publicar suas aplicações independente do Heroku suportá-la nativamente)

heroku buildpacks:set http://github.com/noliar/dotnet-buildpack.git

Vale dar uma passada lá na interface do Heroku e verificar se a mesma está conectada a seu repositório git para que as coisas fluam logo na primeira tentativa.

Na sequência execute os seguintes comandos

heroku git:remote -a your-app-name
git commit -am "Setup for Heroku"
git push heroku master

Neste momento você irá acompanhar uma série de instruções referentes ao deploy de sua aplicação e no final você encontrará o seguinte resultado

remote: Verifying deploy... done.

Agora abra sua ferramenta favorita para testes de APIs (no meu caso Postman) ou a aplicação cliente diretamente e contemple os resultados!

Caso você tenha problemas com o buildpack selecionado você pode removê-lo ou limpar todos os buildpacks relacionados com os comandos

heroku buildpacks:remove http://github.com/jenyayel/dotnet-buildpack.git

ou

heroku buildpacks:clear

E também pode forçar o deploy da aplicação a partir do repositório Git pela própria interface do Heroku.

Bonus! Comando útil!

Você pode controlar a quantidade de Dynos da sua aplicação com o comando

heroku ps:scale web=2

Sendo que nos planos Free (Fique atento aos planos) você só consegue utilizar 1 Dyno e se você inserir web=0 derrubará sua aplicação mas poderá voltar a atividade rapidamente utilizando web=1.

Sempre que atualizar sua aplicação lembre se de dar commit no git e push no git e no Heroku. Se suas alterações não forem refletidas, execute o deploy manualmente.

Importante: Este artigo é dedicado ao amigo Arthur Baptista que sofreu um pouquinho tentando fazer esse deploy mas acho que agora estará salvo para sempre!

É isso aí! Até a próxima! 😉

AngularJS 1 – 2 Conceitos Básicos

Olá pessoas,

Agora que você já instalou o ambiente dev para conseguir escrever suas primeiras aplicações SPA com Angular e provavelmente já deve ter tentado escrever algo e se enrolado bastante com o que vai aonde e que raios são esse monte de arquivos JS vamos entender os conceitos básicos do Angular (sem enrolação) e começar a produzir algo.

Atenção: Este post longo e pode parecer chato em alguns pontos, vou me esforçar para melhorar isto, entretanto é muito importante que você leia e entenda como funciona o framework antes de sair testando uma série de coisas nos próximos posts;

Acompanhe abaixo os links da série:

Série AngularJS1

1. Configurando seu ambiente Windows
2. Conceitos Básicos

Como funciona o Angular e o que é MVW? 

O AngularJS é um framework baseado no pattern MVW (Model, View, Whatever) onde a Model é a camada que representa as entidades da app, as Views seriam a camada de apresentação e Whatever seria qualquer coisa que você queira chamar as Controllers e os Services. Se você quer uma definição bacana de padrões arquiteturais de projetos veja este link.

Na verdade gosto de imaginar que a model seria os objetos $scope, as views são o nosso bom e velho html e as controllers são as controllers mesmo. E se for extremamente necessário definir o que seriam os services (se você realmente se incomoda) eu não os colocaria em lugar nenhum nesse contexto porque para o angular services são apenas objetos reutilizáveis dentro da aplicação .

Views, Diretivas, Controllers e Services

Sem muita enrolação, vamos definir o que faz cada coisa:

Views – São suas velhas e boas amigas tags html. Nada de especial, só o de sempre mesmo.

Diretivas – Existem vários lugares aonde você pode conseguir uma definição mais polida de diretivas (a documentação oficial, por exemplo), eu prefiro definir como atributos especiais que grudam as Views (seu html) com as controllers do Angular. Veja os exemplos:

 
<!doctype html>
<html ng-app>
<body>

<div>
        <label>Name:</label>
        <input type="text" ng-model="yourName" placeholder="Enter a name here">

<hr>


<h1>Hello {{yourName}}!</h1>

    </div>

</body>
</html>

Perceba nas linhas destacadas vemos dois elementos que não pertencem ao nosso bom o velho html, as diretivas ng-app e ng-model.

ng-app: “Sinaliza” para o Angular que a partir daquele ponto é iniciada nossa aplicação.

ng-model: Liga o valor inserido no campo com o valor apresentado entre chaves (curly braces ou double mustaches). Quando um valor é passado de dentro do framework para a view chamamos isso de Data-binding. Calma.. Vamos falar mais disso depois.

Diretivas mais comuns

ng-repeat: Itera entre elementos criando uma repetição de resultados. Muito comum quando você tem uma lista de objetos e quer mostra-los na View.

<ul>

<li ng-repeat="cor in cores">
        {{cor}}
    </li>

</ul>

ng-click: Invoca o evento click de uma objeto na View. Muito comum quando queremos executar uma função presente em nossa controller.

<button class="btn btn-primary" ng-click="btnClick()">Click aqui</button>

ng-show / ng-hide: Exibe ou oculta um determinado item da view.

<ul>
    <!-- ng-show mostrará somente se a função retornar true -->

<li ng-show="somentePares()">{{numeros}}</li>

</ul>

ng-disable: Inclui o atributo disable no elemento html da view.

<form class="navbar-form navbar-left" role="search">

<div class="form-group">
        <!-- ng-model 'grudará' o valor de nossa busca numa variável do Angular -->
        <input type="text" class="form-control" placeholder="Buscar" ng-model="busca" required>
    </div>

    <!-- graças a ng-disabled o botão ficará desativado se não houver valor no campo busca -->
    <button type="submit" class="btn btn-default" ng-disabled="!busca" ng-click="btnBuscar(busca)">Submit</button>
</form>

ng-if: Executa uma comparação exibindo o elemento em questão caso essa verificação seja verdadeira.

<!-- esta div so aparecerá se o ususario ja estiver cadastrado -->

<div class="alert alert-warning" role="alert" ng-if="usuarioCadastrado()">

<h2>Usuário já cadastrado!</h2>

</div>

<!-- esta div so aparecerá se o usuário NÃO estiver cadastrado -->

<div ng-if="!usuarioCadastrado()">

<h2>Cadastrado de usuário</h2>


<form class="form">

<div class="form-group">
            <input type="text" class="form-control" placeholder="Seu Nome" ng-model="usrNome" required>
        </div>


<div class="form-group">
            <input type="text" class="form-control" placeholder="Seu Email" ng-model="usrEmail" required>
        </div>

        <button type="submit" class="btn btn-default" ng-disabled="!busca" ng-click="cadastrarUsuario()">Submit</button>
    </form>

</div>

Você deve ter percebido nos casos da ng-click e ng-show/hide que diretivas suportam funções e condições como valor.

Mostrarei depois: Você também pode criar suas próprias diretivas. Isso é muito bom em termos de “componentização” (não, essa palavra não existe) de elementos. Por exemplo, você pode criar uma galeria de fotos padrão e simplesmente chamar a diretiva passando as fotos:

<!-- Esperamos que ao renderizar a diretiva o Angular mostre a galeria e um botâo para adicionar uma nova foto -->
<minhaGaleria datasource="fotos" add="foto"></minhagaleria>

Mas não vamos apressar as coisas, este post já está ficando bem grande graças a complexidade das diretivas.

Controllers – Digamos que você queira escrever uma calculadora. É justo dizer que você deveria escrever as operações em algum lugar que não fosse a view:

Teste este exemplo no Plunker.

Perceba que usamos algumas diretivas que você já viu e outras que você ainda não conhecia. A diretiva ng-controller sinaliza para o Angular que a partir daquela tag o conteúdo está vinculado a controller específica.

Services – Como eu disse anteriormente services são “pedaços de código reutilizáveis” dentro da sua aplicação.

Vamos fazer algumas adaptações na tag scripts no exemplo anterior para usarmos services:

Teste este exemplo no Plunker.

Injeção de dependências (DI – Dependency Injection)

Não sei se você percebeu mas para usar nosso service, foi necessário chamá-lo como parâmetro dentro do controller e obviamente adiciona-lo como source na nossa index.html. Isso acontece porque o Angular funciona com injeção de dependências, ou seja, se você quer usar um pedaço de código que não e em seu contexto atual (ex. Quero chamar um service na minha controller) você precisará injetar uma chamada para este código na função de seu contexto. Pareceu difícil né? Na verdade não é… eu só não consegui explicar isso de maneira mais simples..

Serviços do AngularJS (Built-in Services)
No mundo real nós sabemos que os problemas serão muito mais complexos que estes e você com certeza deve estar morrendo de vontade de chamar uma API dentro de um service e passar os resultados para dentro de uma controller pois isso é o que a maior parte das aplicações fazem.

Mas antes você deve saber que o Angular possui seus próprios services. Os mais comuns são $http, $location e $window:

$http – Realiza chamadas via protocolo http. Você verá bastante isso quando for se comunicar com uma API externa, seja para simplesmente pegar alguns valores ou separar as chamadas de um CRUD inteiro de uma entidade.

$location – Esta é responsável por alguns recursos de navegação é um service baseado no window.location do JS. No caso do Angular, window.location se tornaria $location.path().

$window – Responsável por recursos da janela ativa do navegador,o que em JS comum seria um alert(), aqui no Angular seria um $window.alert();

Mas vamos ao que interessa! No exemplo abaixo eu mostro como fazer uma chamada para a API externa Numbers. Esta API retorna curiosidades sobre os números. Basta informar o número e nosso Service enviará uma chamada Http.Get para a API e a mesma retornará um JSON com a resposta:

Teste este exemplo no Plunker.

Nota: O Plunker exige chamadas https e a Numbers API só suporta chamadas http. Para testar esse código copie e cole do Plunker para seu editor favorito, salve e teste em seu navegador.

Mostrarei depois: Se você já tem conhecimento prévio de AngularJS você deve estar se perguntando porque eu não falei das diferenças entre Service e Factory e porque eu não comentei sobre os objetos do tipo $promise e da importância do .then() quando trabalhamos com chamadas HTTP. A resposta para sua pergunta é: Aguarde e confie! Este assuntos serão abordados em posts mais densos, este post já ficou longo demais e meu objetivo é só te mostrar como as coisas se encaixam antes de começarmos a escrever posts baseados em exemplos práticos (do mundo real).

Por enquanto, é só tudo isso! 😉

AngularJS 1 – 1 Configurando seu ambiente Windows

Olá pessoas,

Pretendo escrever uma série de posts ajudando quem quer começar a desenvolver aplicações web utilizando AngularJS, o famoso framework do Google, de maneira prática, rápida e o mais próxima possível do que uso no meu dia-a-dia.

Acompanhe abaixo os links da série:

Série AngularJS1

1. Configurando seu ambiente Windows
2. Conceitos Básicos

Tenho percebido que alguns colegas sofrem ao instalar seu ambiente dev para trabalhar com aplicações usando NPM, Bower, e nosso geradores do Yeoman no Windows.

Pequeno Glossário antes de começar:

Grunt e Gulp: Grunt e Gulp são automatizadores de tarefas. A grosso modo, eles são os responsáveis por minificar todos seus arquivos e deixar tudo pronto numa linda pasta “dist”, da onde você irá simplesmente publicar seus arquivos em seu servidor de hospedagem.

NPM: NPM (Node Pakage Manager) é um repositório (gerenciador de pacotes) de instalações do Node.js. Para quem ja teve experiência com OSX e Linux, é como se fosse um apt-get da vida…

BOWER: Bower também é um repositório. Em geral usamos os dois, mas você pode usar só o Node ou somente o Bower, de qualquer forma, quando você inicializar seu projeto com o gerador Angular do Yeoman ele irá criar as pastas bower_components e node_modules.

SASS e Compass: SASS é o que eu considero assim uma evolução natural do CSS. Imagine você poder variáveis dentro de seu css, ao passo que “background-color:#ccc;” se torne uma váriavel chamada: “.aquele-bg-cinza”. Existe toda uma possibilidade de você “componentizar”elementos do seu CSS.

Yeoman: Nosso querido Yeoman é uma ferramenta capaz de acelerar a criação de projetos “do zero”, por meio de “generators”. Imagine que chato ter que iniciar toda vez um projeto criando todas as pastas, configurar dependências de seus módulos NPM e componentes do Bower, enfim um super trabalho duro. E graças ao Yeoman, desnecessário.

Agora que você já sabe do que estamos falando, vamos começar a fazer as coisas funcionar. Hoje me dia você não precisa mais se revirar e se debater tantando configurar variáveis de ambiente no windows:

Windows-build-tools

Antes de mais nada instale o Windows-build-tools em seu sistema caso contrário você tera problemas com várias dependências do node como por exemplo o node-sass.

Execute o seguinte comando em uma janela do PowerShell com permissões de Administrador:

npm install --global --production windows-build-tools

1 Instale o Git for Windows

Basta acessar o este link, baixar e instalar o cliente do Github para Windows.

2 Instale o Node.js

Basta acessar este link e escolher uma versão estável do Node.js para Windows. Repare que o próprio instalador já configura as variáveis de ambiente para você.

3 Instale o Ruby Installer

Sim, você vai precisar do Ruby for windows para poder instalar o Compass via gem (repositório de instalações do Ruby, semelhante ao NPM para JavaScript ou o PIMP para Python)

Basta acessar este link e baixar o instalador do Ruby para Windows.

4 Reinicie seu PC

É extremamente recomendado que você reinicie seu PC neste ponto para conseguir executar os comandos do Ruby e do Node.

5 Verifique se o Node e o Ruby foram instalados

Se tudo deu certo até aqui, os comandos abaixo devem retornar a versão atual do Node e do Ruby instados:

git --version

npm - v

ruby -v

Seu resultado deve ser algo parecido com isto:

5 Instalando Compass

Agora vamos instalar o Compass usando gem (nosso npm do ruby).

Antes de mais nada, vamos adicionar o caminho pelo qual será pesquisada nossa gem.

gem sources --add http://rubygems.org/

E em seguida, confirme com [Y] e execute:

gem install compass

OK. Git, Node, Ruby e Compass instalados com sucesso até aqui.

6 Instalando Yeoman

Agora a coisa ficou bem fácil, basta instalar globalmente o Yeoman:

npm install -g yo

E só pra garantir, nós vamos usar o yo doctor para verificar se tudo está instalado como deveria.

yo doctor

E no final ele deve retornar: “Everything looks all right!“.

7 Instalando generator Angular

Angular é um dos generators mais populares no yo, foi desenvolvido pelos próprios yeoman team. Você encontrar generators para outros tipos de app no próprio site do yo, neste link. E você também pode visitar o git do generator Angular neste link.

Para instalar esse generator utilize o seguinte comando:

npm install -g grunt-cli bower yo generator-karma generator-angular

Esse comando bacana faz um monte de coisas na sequencia ele instala globalmente o grunt, o bower, o karma (havia me esquecido de mencionar este. Karma é uma ferramenta de testes para seu código JS) e o generator angular.

Após todo esse trabalhinho (nem foi tão difícil assim…) você pode navegar até a pasta aonde seu projeto será criado e inciá-lo com o seguinte comando:

yo angular [nome-do-seu-app]

Então o Yeoman aparecerá e te fará umas perguntas sinistras, de primeiro momento responda não para o uso do Gulp (experimental) e responda sim para o uso de Sass, compass, e a versão sass do Bootstrap.

Feito isso veja que os arquivos de seu projeto já foram criados e você poderá testar seu projeto com o seguinte comando:

grunt serve

Caso você encontre erros você ainda pode forçar a execução do projeto com:

grunt serve --force

E quando quiser publicar seu projeto basta utilizar o comando:

grunt

Você verá que foi criada uma pasta “dist” na raiz de seu projeto. É lá que você encontrará todos os arquivos minificados para publicação em seu servidor de hospedagem seja ela qual for.

Por hoje é só.

Sim isso será uma série sobre Angular1 e sim, eu já estou estudando Angular2 e pretendo em breve começar a compartilhar mais sobre… Sim também falarei sobre Ionic Framework. 😉

Este post é dedicado aos amigos Gabriel Gois e Apolo Roberto e acredito que escrevendo e guardando isso em algum lugar me ajudarei e os ajudarei.

Criando documentações em reStructuredText com Sphinx – Parte2

Olá, no último post, você viu:

1. O que é Sphinx
2. Como instalar o Sphinx
3. O que é reStructuredText e como é sua sintaxe
4. Como configurar um tema em sua documentação

Nesta parte do post vou mostrar como ativar o recurso de “live reload” para facilitar o trabalho durante a escrita de sua documentação, como fazer o upload da documentação para um repositório Git e publicar essa documentação utilizando o Read The Docs.

Utilizando atualização em tempo real de navegador sphinx-autobuild

Para instalar o sphinx-autobuild siga os seguintes passos:

1. Execute o seguinte comando para instalar o python live reload:

pip install https://github.com/lepture/python-livereload/archive/master.zip

2. Em seguida, instale o sphinx-autobuild via pip:

pip install sphinx-autobuild

3. Altere seu arquivo Makefile inserindo mais uma task do sphinx:

.PHONY: livehtml
livehtml:
 sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

E pronto.. Você pode abrir seu navegador e acessar: http://127.0.0.1:8000/ e perceberá que os arquivos .rst estarão em modo –watch, ou seja, assim que salvar um documento seu navegador ira atualizar a página refletindo as alterações automaticamente.

Fazendo upload da sua documentação para o git

Neste tutorial eu suponho que você conhece o Github e sabe como criar um repositório, dar um commit e push em seus arquivos. Caso tenha dificuldades de uma olhada neste link.

1. Crie um repositório novo no git:

2. Execute seu primeiro commit e push de seus arquivos no repositório utilizando os comandos:

3. Agora você deverá acessar a opção “Settings” dentro do repositório no Git e na sequencia acessar “Webhooks & Services”

4. Clique no botão “Add Service” e procure por “ReadTheDocs”:

5. Pronto. Terminamos a parte do Github, agora vamos para o ReadTheDocs.

Importando e disponibilizando sua documentação com ReadTheDocs

Nesta parte vamos importar os dados de nosso repositório no Github e disponibilizar nossa documentação online.

1. Acesse o ReadTheDocs e efetue login ou crie uma conta:

2. Clique no botão “Import Repository” e selecione o repositório onde está armazenada sua documentação:

3. Em seguida, selecione “Next” e aguarde uns instantes. Atualize a página algumas vezes para verificar se os processos passaram sem nenhuma falha.

4. Volte para página principal “Overview” e você verá que o status de build da sua documentação mudou para “Passed”.

5. Agora basta acessar o endereço localizado em “Short Urls” e compartilhar esse endereço.

O ReadTheDocs possui features para configuração avançada de temas e apontamentos de domínio. Isso conclui nossa experiência com Sphinx, reStructureText e ReadTheDocs!

Até a próxima!  😉

Criando documentações em reStructuredText com Sphinx – Parte1

Olá você ja deve ter percebido uma mudança no postal ASP.NET com relação aos tutoriais do .NET Core.

Hoje eu estava lendo e re-lendo os tutoriais sobre WebAPI utilizando o Net Core e percebi que a interface do portal tinha mudado, foi então que depois de dias eu me atentei para o rodapé da página que diz assim

Built with Sphinx using a theme provided by Read the Docs. Documentation licensed under CC BY 4.0.

Bingo! estão experimentando uma forma nova de postar a documentação e os tutoriais do Net Core. E foi ai que eu descobri o Sphinx, uma ferramenta bem popular entre a galera do Python que usa uma linguagem de marcação conhecida como reStructuredText ou .rst que pode te ajudar bastante na hora de gerar a documentação de seus software seja ele na linguagem que for.

Se esse assunto te interessa e você quer escrever uma página de documentação igual essa aqui que eu escrevi, leia este artigo até o fim.

“Less talk, more code”

1. A primeira coisa que você vai precisar é instalar o Python na sua máquina:

brew install python

2. Depois vc vai instalar o Sphinx:

pip install sphinx

O pip é um gerenciador de repositórios PY assim como o NPM com o Node.js.

3. A seguir, você deverá criar a pasta na qual deseja gerar sua documentação e inicializar o sphinx:

mkdir docs
cd docs
sphinx-quickstart

Importante – Atualizado (01/08/2016): Caso você tenha problemas ao executar o comando sphinx-quickstart, talvez você deva abrir o seu .bash_profile:

touch ~/.bash_profile; open ~/.bash_profile

Inserir as seguintes variáveis e salvar o arquivo:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

E em seguida, executar o comando abaixo:

source $HOME/.bash_profile

Agora você pode continuar com o comando sphinx-quickstart que as coisas funcionarão como esperado. Encontrei a solução deste problema nesse link.

4. Bom agora vai começar um longo Quiz aonde você deverá responder Y ou N para as milhares de perguntas que o Sphinx fará. Como você me deu algum crédito e está lendo isso, vou compartilhar contigo o caminho das pedras:

Enter the root path for documentation.
> Root path for the documentation [.]:
— Aperte enter.

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]: y
— Marque N para essa opção, pois vamos usar o VSCode com uma extensão bem bacana.

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 [_]:
— Aperte enter, Sorria e acene.

The project name will occur in several places in the built documentation.
> Project name:
> Author name(s):
— Nome do projeto e autor.

Sphinx has the notion of a “version” and a “release” for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don’t need this dual structure,
just set both to the same value.
> Project version:
— A versão inicial da sua documentação, normalmente: 0.0.1 ou 0.0.1a

> Project release [0.0.1]:
— Aperte enter.

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]:
— Isso é bem bacana! Quer a interface da sua documentação em português? Informe pt_BR

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]:
— Aperte enter.

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]:
— Aperte enter.

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]: y
— Quer que os usuários consigam gerar arquivos ePub da sua documentação? Y!!!

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write “todo” entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
— Marque Y para a primeira opção e não para as demais. Eu havia marcado Y para a criação os arquivos .nojekyll (Se você não sabe o que é Jekyll, clique aqui) e algumas coisas deram errado então sugiro que você continue seguindo o caminho das pedras.

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]: y
— Você não quer excluir os usuários de Windows da possibilidade de alterar e gerar sua documentação né? Então aceite essas duas opções.

Ok, se tudo deu certo você está quase lá!

5. Vamos gerar a documentação e na sequência eu ja vou explicar como vc vai editar tudo. Execute o comando:

make html

6. A sua estrutura de arquivos deverá se parecer com isto:

7. Agora abra o arquivo index.html em build/html:

Show! As coisas estão funcionando!

“Ah, mas não ficou igual ao seu!” Calma… vamos chegar lá.

Entendendo os arquivos e como funciona o reStructuredText (rst)

Você encontrará 2 arquivos importantes o conf.py que é o responsável por armazenar toda aquela configuração dos passos anteriores e o index.rst

8. Abra o index.rst e adicione novas linhas baixo: (Atenção para a identação, se você errar a identação seus htmls não serão gerados)

9. A partir do momento que inserimos 2 tópicos em index.rst, deveremos criar 2 arquivos com o mesmo nome (exatamente igual, rst é case-sensitive) na mesma pasta, ou seja, intro.rst e about.rst.

Como funciona reStructuredText?

Agora vamos entender como funciona o reStructuredText. Para quem já está acostumado a escrever mardkdown acredito que seja mais fácil se adaptar:

Cabeçalho da seção 
==================
Sub-cabeçalho da seção 
----------------------

Exemplo de cabeçalhos

- Primeiro item- Segundo item- Um sub item

Exemplo de listas simples

.. code-block:: js
   :caption: js
   :name: js 
   :lienos: 
   
   //Algum código em JS

Exemplo de Block de código

Maneiras Práticas de escrever reStructuredText (.rst)

De fato, pode parecer complicado mas depois de uns minutos você começa a se acostumar e acaba percebendo que é bem mais ágil e limpo do que usarem editores de html. Caso você queira conhecer mais sore reStructuredText acesse este link.

Você também pode utilizar o  Online reStructuredText Editor, entretanto este editor não contemplará blocos de código.

Outra forma bacana de trabalhar é usando uma extensão para Visual Studio Code desenvolvida por Lex LI.

Instalando o rtd_theme e outros temas

Para instalar aquele o rtd_theme (o que usei neste exemplo) siga os seguintes passos:

1. Baixe o tema via pip:

$ pip install sphinx_rtd_theme

2. Insira esta linha em seu arquivo conf.py:

import sphinx_rtd_theme

3. Altere as variáveis em seu config.py conforme abaixo:

html_theme = "sphinx_rtd_theme"

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

E pronto! Sua documentação já está bem parecida com a que eu escrevi como exemplo. Para saber mais sobre o rtd_theme clique aqui e para saber mais sobre demais temas para o Sphinx, clique aqui.

Conclusão

Sphinx é uma ferramenta extremamente ágil e reStructuredText é uma linguagem fácil de se acostumar, principalmente se compararmos com documentações criadas puramente em texto. As funções de exportação para html, pdf e ePub são muito legais e o suporte a temas e a facilidade ao alterar o conteúdo das páginas é sem duvida uma evolução. Entretanto o suporte a editores ainda torna trabalhoso o upload de imagens e a inserção de blocos de código.

Este artigo acabou ficando extremamente longo, então vou encerrá-lo por aqui. No próximo artigo vou explicar como utilizar uma função de “live reload” para facilitar a edição de sua documentação, publicar num repositório Git e utilizar o Read the Docs para renderizar e até apontar um domínio para sua documentação.

Até a proxima 😉

Desenvolvendo ASP.Net MVC diretamente no Mac.. Pode? Pode!

Hoje acordei pensando em colocar em prática a missão de desenvolver uma aplicação web utilizando somente o Visual Studio  Code diretamente no Mac OSX sem abrir minha VM de windows e recorrer ao Visual Studio de maneira convencional.

Isso porque após ter focado no desenvolvimento frontend e ter mergulhado no mundo do node.js e do AngularJS eu realmente sonhei com o dias aonde eu poderia construir uma WebAPI com a mesma facilidade que se constrói uma app web com Yeolman.

DNU, DNX, DNVM e nada mais disso é verdade graças ao .NET CLI

Fato, eu não inventei nada. Quem alimentou essa esperança em mim foi o @vquaiato, nesse post, nesse, e nesse, onde ele explicou o que era o DNU, DNX e o DNVM. Caso você queira entender melhor esses carinhas, acesse os posts e leia com mais calma. Basicamente o DNX era o ambiente de execução do SDK, DNU era o gerenciador de pacotes e o DNVM era o gerenciador de runtimes do dotNet.

Complicado né? Mas relaxa porque o @giovannibassi mostrou nesse post, depois de um bom tempo que agora tudo ficou mais fácil você só precisa do .NET CLI.

“Less talk, more code!”

Configurando seu ambiente de desenvolvimento

Agora que já expliquei o que eu queria, porque e quem me ajudou, vamos compartilhar logo a maneira de fazer esse negócio funcionar:

1. Instale o homebrew no seu Mac com o seguinte comando (Caso tenha problemas, acesse o site oficial do homebrew):

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

2. Execute os seguintes comandos em seu terminal:

˜$ brew update
˜$ brew install openssl
˜$ brew link --force openssl

3. Instale o .NET Core a partir deste link

4. Instale o Node.js caso já não tenha instalado.

5. Assim que terminar de instalar o Node.js instale o generator Yeoman para dotnet via NPM. Volte ao terminal e execute o comando:

npm install -g generator-aspnet

Importante: O próprio npm e a comunidade do Node.js não indica utilizar sudo antes dos comandos, entretanto para fins de teste você pode se livrar de problemas de acesso diretórios facilmente utilizando sudo + comando do npm. Agora se você quer realmente aprender a resolver este problema de permissão ao instalar pacotes via npm, acesse este link.

Iniciando e executando um novo projeto

1. Abra o terminal, acesse sua pasta de projetos utilize os comandos:

mkdir aspnet-mvc
cd aspnet-mvc
yo aspnet

2. Uma série de coisas irão acontecer no seu terminal, fique atento para possíveis erros durante este processo. Neste momento o Yeoman generator vai acessar diversos repositórios e preparar todos os arquivos de seu projeto. Para executar sua aplicação, você deverá utilizar os comandos (na minha opinião, bem auto explicativos):

dotnet restore
dotnet build
dotnet run

Hey! Você cansou de ver essa linda página em seus projetos, certo? Ótimo! As coisas estão funcionando como deveriam; mas para nos certificar, vamos alterar alguma coisa nesse projeto.

3. Abra seu Visual Studio Code (caso não tenha instalado, clique aqui) e acesse a pasta de seu projeto (command + O). Você também precisará da extensão do C# para o Visual Studio Code. Caso o mesmo não sugira o download acesse este link.

4. Agora vamos editar a action About dentro de HomeController.cs. Vamos inserir algo bem proximo do que antes você fazia com ViewBags:

ViewData["SomeData"] = "pseudo viewbag msg..";

5. Agora vamos alterar a view About.cshtml a fim de refletir a alteração da action About:

<p>Test data from controller:
<strong>@ViewData["SomeData"]</strong></p>

6. Tudo extremamente simples, agora a parte triste: Infelizmente ainda precisamos recompilar o C#, então ainda não temos recursos bacanas como livre reload; mas você perceberá que ainda sim é muito mais rápido do que você estava acostumado no ASP.NET MVC dentro do Visual Studio. Volte a tela do terminal e utilize (control + c) para parar a instancia atual de seu site e execute novamente o comando:

dotnet run

7. Pronto.. Graças ao .Net Core, você conseguiu criar um projeto ASP.Net MVC sem auxilio do Visual Studio, utilizando somente o .NET CLI, Visual Studio Code e o Yeoman!

Referências

Building Projects with Yeoman
ASP.NET 5 – Primeiros passos (dnvm, dnu, dnx e yeoman)
Adeus DNX, bem vindo .NET CLI

Conclusão

Podemos perceber que a Microsoft está super alinhada com tecnologias extremamente ágeis que já fazem parte da vida de um montão de gente como: Node.js/NPM, Bower, generators do Yeoman etc.. isso é muito bom! Acredito que o .Net Core veio para integrar e enxugar uma série de soluções que já eram boas e tem tudo para ficar ainda melhores!

Legal né?! 😉

Suposto comprador aplica fraude nos portais Mercado Livre e BomNegócio/OLX

Olá pessoas,

Venho por meio desta notificar uma fraude em que quase caí (mais uma), desta vez tentando vender meu notebook no Mercado Livre.

O golpista chamado, na maioria das vezes como “Gabriel Lucas” ou “Alessandro Balen” pede para fechar negócio nos sites via e-mail normalmente usando os e-mails “jonas5776@airpost.net” ou “glucas847@gmail.com”.

No meu caso, ele disse estar nos EUA e pediu para se comunicar em inglês, mas existem relatos de outras pessoas onde o golpista usou tradutores para se comunicar, denunciando o português falho.

Durante as negociações ele sempre diz precisar enviar o produto para a mãe (filha, irmão ou algum parente) e após solucionar algumas dúvidas e fechar negócio, envia um e-mail falso tentando imitar portais de pagamento como PagSeguro, Paypal ou o próprio MercadoPago. Nesta mensagem o nome do destinatário pode variar mas o endereço é sempre o mesmo:

Nome: Adewole Tolu
Endereço:Sabo motor park
Código Postal: 210271
Cidade: Ogbomosho
Estado: Oyo
País: Nigéria

Desconfiei da procedência desta negociação e resolvi pesquisar o endereço, onde encontrei várias referências para a fraude, inclusive um post bem bacana do colega Flávio St Jayme do blog “Pausa Dramática“; Você pode encontrar o post clicando aqui.

Também encaminhei este relato para o canal de denúncia da Policia Federal e se você quase caiu ou caiu neste golpe, informe-os imediatamente pelo e-mail: crime.internet@dpf.gov.br

UPDATE (27/11/2015)
E o golpe continua… Já se passou mais de um ano que criei este post e como podem ver o golpe ainda é aplicado da mesma forma. As vezes chego a pensar que existem dificuldades técnicas ou falta de interesse da parte dos portais e da divisão de crimes virtuais da DPF.. 😦

UPDATE (07/03/2018)
Dois anos após visitas muitas visitas nesse post e muitos comentários e não se sabe ao certo como os órgãos responsáveis pela nossa segurança online atuam para combater esse tipo de fraude. O que posso relatar é que tanto a SaferNet Brasil e a Policia Federal não dão mais suporte a esse tipo de denúncia. Resta denunciar nas próprias plataformas onde a tentativa de fraude foi detectada.

Mas não descansaremos e espalharemos essas informações para evitar que outros usuários sejam vítima desse tipo de fraude!

Não me cansarei de “enxugar gelo”, (termo muito comum e absurdo que já ouvi para este e muitos outros casos de impunidade no Brasil) não me incomodo de gastar alguns minutos do meu dia reportando esse tipo de coisa.

Abraço a todos! 😉