Typedoc + Angular + Bitbucket
Tags: typescript, devops, pipelines
Published: 2020-11-09 17:56:00

---
title: Typedoc + Angular + Bitbucket
published: true
description: Pipelines con bitbucket, angular y nuestra documentación generada.
tags: typescript, devops, pipelines
//cover_image: https://direct_url_to_image.jpg
---
La verdad es que escribir código es algo increíble. Es de las pocas formas en las que podemos crear algo nuevo e incluso cambiar el mundo desde nuestra silla con una computadora. Ahora bien, con la evolución de la industria cada día necesitamos hacerlo mejor y más rápido. Es allí cuando debemos recurrir a la automatización y conceptos como [CI/CD](https://es.wikipedia.org/wiki/CI/CD) (Continuos Integration / Continuos Deployment) toman peso.

![https://www.freshleafmedia.co.uk/assets/media/bitbucket-pipeline_blogThumb.png](https://www.freshleafmedia.co.uk/assets/media/bitbucket-pipeline_blogThumb.png)

Como resultado de estas necesidades [Atlassian](https://atlassian.net/) ha implementado [Pipelines](https://es.wikipedia.org/wiki/Arquitectura_en_pipeline_(inform%C3%A1tica)) en su producto [Bitbucket](https://bitbucket.org/product/) por lo que reciben el nombre de [¨Bitbucket Pipelines¨](https://bitbucket.org/product/es/features/pipelines) (si, no lo pensaron demasiado).

Como comente en mi artículo anterior ([Git Hooks ¿Qué son y para que?](https://medium.com/@fjbatresv/git-hooks-qu%C3%A9-son-y-para-que-41fa29b65c7b)), llevo desde marzo 2020 trabajando como freelance para una empresa y pues parte la aventura que empezó como una asesoría, hoy me ha llevado al área de DevOps y a crear estas integraciones para que el equipo de desarrollo funcione de forma más eficiente. 

---

El ejemplo que les explicaré hoy es un proyecto de [Angular](https://angular.io/) el cual hemos integrado a [Firebase Hosting](https://firebase.google.com/docs/hosting) con nuestro flujo de ramas basado en [GitFlow](https://www.atlassian.com/es/git/tutorials/comparing-workflows/gitflow-workflow).

Lo primero que explicaré es como creamos nuestra documentación de forma automática mediante [Typedoc](https://typedoc.org)

![https://firebasestorage.googleapis.com/v0/b/fjbatresv-website.appspot.com/o/Blogs%2FSin-ti%CC%81tulo-1.png?alt=media&token=3554e786-131a-4c89-94bf-edd30f5271f2](https://firebasestorage.googleapis.com/v0/b/fjbatresv-website.appspot.com/o/Blogs%2FSin-ti%CC%81tulo-1.png?alt=media&token=3554e786-131a-4c89-94bf-edd30f5271f2)

## [Typedoc](https://typedoc.org)

Es una librería destinada para proyectos de TypeScript la cual nos permite generar una documentación desde los comentarios del código. Si bien es un poco cansado poner comentarios en nuestro código, la verdad es que cuando la aplicación llega a cierto punto de crecimiento se vuelve una necesidad. 

El uso es simple, necesitamos crear un archivo en la raiz de nuestro proyecto que tenga la configuración con la que crearemos nuestra documentación. Algo así:

```json
{
    "out": "docs",
    "tsconfig": "./tsconfig.app.json",
    "theme": "./node_modules/typedoc-bitbucket-theme/dist/",
    "plugin": "typedoc-plugin-markdown",
    "exclude": "**/*+(index|.spec|.e2e).ts",
    "inputFiles": ["./src"]
}
```

En este caso específicamente estamos usando un tema o plantilla para bitbucket y un plugin que genera los archivos en formato [Markdown](https://es.wikipedia.org/wiki/Markdown). De igual manera estamos excluyendo a los test que se crean para los componentes de [Angular](https://angular.io) y estamos setteando la configuración del [TypeScript](https://es.wikipedia.org/wiki/TypeScript) desde nuestro tsconfig.app.json para que reconozca algunos ajustes que hemos hecho. Por último vemos que se coloca una lista con los directorios desde los que leerá los archivos y un dato para el nombre nombre del directorio en el que creara la documentación.

Para ejecutarlo solamente debemos correr el siguiente comando:

```bash
npx typedoc
```

## Ambientes

En este escenario trabajamos con 4 ambientes los cuales teníamos que configurar previamente en el proyecto.

- Develop
- Staging
- SandBox
- Production

Para el uso de estos despliegues necesitamos un token de [Firebase CLI](https://firebase.google.com/docs/cli) que podremos generar con el comando

```bash
firebase login:ci
```

![https://res.cloudinary.com/lumigo-production/w_800,h_400,c_fit/fl_lossy,f_auto/wp-website/2020/01/devops-1982x991-1.png](https://res.cloudinary.com/lumigo-production/w_800,h_400,c_fit/fl_lossy,f_auto/wp-website/2020/01/devops-1982x991-1.png)

## Tipos de Pipelines

En este caso hemos implementado 2 tipos de pipelines, uno basado en la creación/actualización de los [PullRequest](https://www.atlassian.com/es/git/tutorials/making-a-pull-request) y uno en el merge de las ramas. Para esto usamos una rama por ambiente y una rama por cada tarea de desarrollo que se realiza.

Algo importante antes de entrar en estas configuraciones son 2 llaves que usaremos debemos agregar:

- $FIREBASE_TOKEN: Token generado con el comando anterior.
- $SENTRY_TOKEN: Token de autenticación creado en [Sentry](http://sentry.io/).

### Por [PullRequest](https://www.atlassian.com/es/git/tutorials/making-a-pull-request)

En este caso buscamos utilizar los nuevos canales de pruebas que nos ofrece Firebase Hosting. Por lo que debemos agregar la configuración al archivo **bitbucket-pipelins.yml** de la siguiente manera:

```yaml
image: node:12.12.0

pipelines:
  pull-requests:
    "**": #this runs as default for any branch not elsewhere defined
      - step:
          name: PullRequest
          caches:
            - node
          script:
            - npm install --quiet
						 - npm run build:$BITBUCKET_PR_DESTINATION_BRANCH
						 - npx firebase use <project_id>
						 - npx firebase hosting:channel:deploy --token "$FIREBASE_TOKEN" "$BITBUCKET_PR_ID"
```

Para está configuración vamos a utilizar 2 [variables](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/) que nos provee de forma automática el ambiente de [¨Bitbucket Pipelines¨](https://bitbucket.org/product/es/features/pipelines) que son:

- $BITBUCKET_PR_DESTINATION_BRANCH: Nombre de la rama a la que se quieren unir los cambios.
- $BITBUCKET_PR_ID: El Id numérico del [PullRequest](https://www.notion.so/fjbatresv/Typedoc-Angular-Bitbucket-1fd7f6fd316e4c8b993b911958982b8f#4a25013e5e1e43e6b548d29dd5f505a9) creado por [BitBucket](https://www.notion.so/fjbatresv/Typedoc-Angular-Bitbucket-1fd7f6fd316e4c8b993b911958982b8f#77a50f3bf1eb4542bb0ea78da2a485f3).

![https://icon-library.com/images/merge-icon-png/merge-icon-png-10.jpg](https://icon-library.com/images/merge-icon-png/merge-icon-png-10.jpg)

### Por [Merge](https://en.wikipedia.org/wiki/Merge_(version_control))

Ahora bien en el caso de que un cambio es aprobado y unido al código de la aplicación de forma definitiva, procedemos a realizar una compilación basada  en el ambiente que corresponde pero, en está ocasión la diferencia está en las ramas **main y develop** las cuales realizan algunos pasos extras.

**Staging y SandBox**

```yaml
image: node:12.12.0

pipelines:
  branches:
    staging:
      - step:
          name: Deploy to staging
          caches:
            - node
          script:
            - npm install --quiet
            - npm run build:$BITBUCKET_PR_DESTINATION_BRANCH
            - pipe: atlassian/firebase-deploy:0.6.0
              variables:
                FIREBASE_TOKEN: "$FIREBASE_TOKEN"
                PROJECT_ID: "<project_id>"
                MESSAGE: "Deploy to hosting from Pipeline"
```

**Develop**

En este caso usamos [TypeDoc](https://typedoc.org/) para generar la documentación y después actualizamos la wiki del repositorio mediante un push de git. Para este proceso necesitamos los siguientes parámetros:

- $AUTH_USER: El nombre de usuario que tengamos en BitBucket.
- $AUTH_PASSWORD: La contraseña del usuario correspondiente.
- $AUTH_NAME: Nombre que el usuario utilizará para realizar el commit.
- $AUTH_EMAIL: Correo Electrónico que utiliza el usuario.

```yaml
image: node:12.12.0

pipelines:
  branches:
    develop:
      - step:
          name: Deploy to Development
          caches:
            - node
          script:
            - npm install --quiet
            - npm run build:develop
            - pipe: atlassian/firebase-deploy:0.6.0
              variables:
                FIREBASE_TOKEN: "$FIREBASE_TOKEN"
                PROJECT_ID: "<project_id>"
                MESSAGE: "Deploy to development from Pipeline"
      - step:
          name: Doc generation
          caches:
            - node
          script:
            - npm install --quiet
            - rm -rf docs/ && npx typedoc
            - rm -rf docs/modules && rm -rf docs/interfaces && rm docs/README.md
            - rm -rf wiki && git clone https://$AUTH_USER:$AUTH_PASSWORD@bitbucket.org/<project>/<repository>.git/wiki
            - cp -r docs/* wiki/.
            - cd wiki && git config user.name "$AUTH_NAME" && git config user.email "$AUTH_EMAIL" && git add * && git commit -m "Updating the wiki autogenerated" && git push origin master
            - cd ..
            - rm -rf wiki && rm -rf docs
            - ls
```

**Main**

En este último caso realizamos 3 procesos, el primero es la publicación de la nueva versión del sitio en nuestro hosting con la configuración de producción y después de forma paralela realizamos 2 acciones.

1. Crear una tag: Esto lo hacemos basados en la versión que obtenemos del archivo *package.json* del proyecto en cuestión.
2. Crear un release en [Sentry](https://sentry.io/): En nuestro caso utilizamos [Sentry](https://sentry.io/), ya que aún no contamos con [Firebase Crashlytics](https://firebase.google.com/products/crashlytics?gclid=CjwKCAiA4o79BRBvEiwAjteoYLL2_uhB7bDJzUwHwn2ApcNBUB0MUjvUTtKfu9WKefG0qBUgia4PPhoCkfcQAvD_BwE) para web.

```yaml
image: node:12.12.0

pipelines:
  branches:
		main:
      - step:
          name: Deploy to Firebase Hosting Prod
          caches:
            - node
          script:
            - npm install --quiet
            - npm run build:prod
            - pipe: atlassian/firebase-deploy:0.6.0
              variables:
                FIREBASE_TOKEN: "$FIREBASE_TOKEN"
                PROJECT_ID: "<project_id>"
                MESSAGE: "Deploy to Prod from Pipeline"
      - parallel:
          - step:
              name: Create Tag
              caches:
                - node
              script:
                - npm install
                - git tag -a $(npx pkg-jq -r .version) -m "Tagged on deployment"
                - git push origin --tags
          - step:
              name: Release on Sentry
              caches:
                - node
              script:
                - pipe: sentryio/sentry-new-release:0.3.0
                  variables:
                    SENTRY_AUTH_TOKEN: $SENTRY_TOKEN
                    SENTRY_ORG: "<sentry_org>"
                    SENTRY_PROJECT: "<sentry_project_id>"
```

Si deseas saber más de mi puedes visitar mi página: [https://fjbatresv.com/](https://fjbatresv.com/)