¿Cómo contribuir?

Tips para contribuir con la documentación

Clona el repositorio de Git https://gitlab.com/esnumera/numera-docs.

Crea un archivo markdown en la carpeta que resulte apropiada dentro de docs

Se recomienda esta estructura general:

• convenciones
• numera-app
• nomina
• migrare
• wrapper-neo
• sso

Cada carpeta representa un microservicio.

Una carpeta también puede ser una sección que no es propiamente un servicio, por ejemplo: convenciones

También es válido que exista el archivo directamente como hijo de docs, ejemplo: contribuir.md

Los nombres de archivos y carpetas deben estar en minúsculas, sin caracteres especiales y con guiones medios si tienen más de una palabra.

Cada archivo debe ser registrado en mkdocs.yml bajo la sección nav, se recomienda que la jerarquía del menú coincida con la estructura de carpetas.

En la sección nav podemos indicar cualquier texto para mostrar en el menú de la página, ahí sí podemos usar caracteres especiales y espacios.

148
149
150
151
152
153
154
155
156

nav:
  - Inicio: index.md
  - ¿Cómo contribuir?: contribuir.md
  - Convenciones:
      - Logging: convenciones/logging.md
      - EventBridge: convenciones/eventbridge.md
      - SQS: convenciones/sqs.md
      - Comentarios TODO: convenciones/comentarios-todo.md
      - GraphQLController: convenciones/graphql-controller.md

Títulos

Si no se especifica un título de nivel 1 (h1), se muestra por defecto el texto dado en el bautizo que indicamos en el archivo mkdocs.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Mi título de nivel 1

Texto de documentación que representa un párrafo.

Se recomienda dejar dos líneas en blanco si a continuación va un título.


## Título de nivel 2

Texto de documentación que representa un párrafo.

Bloques de código

Para señalar bloques de código usando la triple commilla invertida ``` al inicio y al final del bloque, cada cual en su propia línea.

Para resaltar la sintaxis, podemos indicar el lenguaje justo al lado de las comillas de apertura, por ejemplo:

```python

Si queremos agregar un título al bloque para representar el nombre del archivo al que pertenece el bloque, usamos title en la mísma línea de las comillas invertidas de apertura:

```python title="ejemplo.py"

Podemos mostrar los números de línea usando linenums="1", donde 1 representa el número desde el cual arranca.

```python title="ejemplo.py" linenums="1"

Podemos resaltar una o varias líneas usando hl_lines="2 6"

```python title="ejemplo.py" linenums="1"

Ejemplo aplicando todo lo anterior:

1
2
3
4
5
6

class Person
    def talk():
        print("Hi")

p = Person()
p.talk()

Pestañas (tabs)

Cada Tab inicia con /// tab | UN_NOMBRE y termina con ///

/// tab | JavaScript

  ```js
  console.log("hola mundo")
  ```

  Esto es un párrafo dentro de una pestaña javascript.
///

/// tab | Python

  ```python
  print("hola mundo")
  ```

  Esto es un párrafo dentro de la pestaña Python.
///

A continuación vemos el ejemplo de tabs aplicado:

console.log("hola mundo")

print("hola mundo")

Gráficas mermaid

Ver documentación oficial de mermaid.

Este un ejemplo de entre los muchos diagramas que podemos hacer con mermaid:

```mermaid

sequenceDiagram
  autonumber
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!