UNPKG

flurix-developer

Version:

Generador de documentación desde comentarios en JS/TS/PY usando Python

139 lines (101 loc) • 3.69 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
# Guía para Desarrolladores ## Estructura del Código El proyecto está organizado de la siguiente manera: ``` flurix-developer/ ├── scripts/ │ └── generate_docs.py # Script principal de generación de documentación ├── package.json # Configuración del paquete npm ├── README.md # Documentación principal └── requirements.txt # Dependencias de Python ``` ## Componentes Principales ### Script de Generación de Documentación (`generate_docs.py`) Este es el componente central del proyecto. Sus principales funciones son: 1. **`extract_js_docstrings_and_code(file_content)`** - Extrae docstrings y código de archivos JS/TS/JSX/TSX - Utiliza expresiones regulares para identificar comentarios JSDoc - Maneja tanto código documentado como no documentado 2. **`generate_markdown_doc(docstrings_and_code, file_path)`** - Genera contenido Markdown a partir de docstrings - Formatea la documentación de manera consistente - Incluye ejemplos de código cuando están disponibles 3. **`save_markdown_file(directory, relative_path, content)`** - Guarda los archivos Markdown generados - Mantiene la estructura de directorios original - Maneja la codificación UTF-8 4. **`generate_md_from_directory(directory_path, output_directory)`** - Función principal que orquesta el proceso - Recorre recursivamente los directorios - Procesa todos los archivos soportados ## Flujo de Trabajo del Código ```mermaid sequenceDiagram participant User participant Script participant Extractor participant Generator participant FileSystem User->>Script: Ejecuta flurix-developer Script->>FileSystem: Lee archivos fuente FileSystem-->>Script: Contenido de archivos Script->>Extractor: Procesa archivos Extractor->>Generator: Docstrings extraídos Generator->>FileSystem: Genera archivos MD FileSystem-->>User: Documentación generada ``` ## Cómo Contribuir ### 1. Configuración del Entorno ```bash # Clonar el repositorio git clone [url-del-repositorio] # Instalar dependencias de Node.js npm install # Instalar dependencias de Python pip install -r requirements.txt ``` ### 2. Estructura de Desarrollo - Mantén la estructura de directorios existente - Sigue las convenciones de nomenclatura actuales - Documenta todo el código nuevo con JSDoc - Añade pruebas para nuevas funcionalidades ### 3. Proceso de Desarrollo 1. Crear una rama para la nueva funcionalidad 2. Implementar los cambios 3. Añadir documentación JSDoc 4. Probar los cambios localmente 5. Crear un pull request ## Convenciones de Código ### Python - Usar Python 3.x - Seguir PEP 8 para estilo de código - Documentar funciones con docstrings - Manejar excepciones apropiadamente ### JavaScript/TypeScript - Usar JSDoc para documentación - Seguir las convenciones de ESLint - Mantener funciones pequeñas y enfocadas - Usar tipos cuando sea posible ## Pruebas Para probar cambios localmente: ```bash # Generar documentación de prueba npm run generate-docs # Verificar la salida ls docs/ ``` ## Depuración ### Problemas Comunes 1. **Error de codificación** - Verificar que los archivos usen UTF-8 - Revisar la configuración del editor 2. **JSDoc no detectado** - Verificar el formato de los comentarios - Asegurar que sigan el estándar JSDoc 3. **Errores de permisos** - Verificar permisos de escritura - Ejecutar con privilegios adecuados ## Recursos Adicionales - [Documentación de JSDoc](https://jsdoc.app/) - [Guía de Markdown](https://www.markdownguide.org/) - [Documentación de Python](https://docs.python.org/3/)