Luis/docs

.github/workflows/ci/logger.py

@@ -0,0 +1,18 @@
+import logging
+
+# create logger
+logger = logging.getLogger("microscope_doc_ci_logging")
+logger.setLevel(logging.DEBUG)
+
+# create console handler and set level to debug
+ch = logging.StreamHandler()
+ch.setLevel(logging.DEBUG)
+
+# create formatter
+formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+
+# add formatter to ch
+ch.setFormatter(formatter)
+
+# add ch to logger
+logger.addHandler(ch)

.github/workflows/ci/quality_check.py

@@ -0,0 +1,10 @@
+import sys
+from logger import logger
+
+mkdocs_build_output = sys.argv[1]
+if mkdocs_build_output != str(0):
+    logger.error('Error building mkdocs. Warnings were found.')
+    raise Exception('Error building mkdocs. Warnings were found.')
+else:
+    logger.info('No warnings found building mkdocs.')
+

.github/workflows/ci/stage.py

@@ -0,0 +1,73 @@
+'''
+    This script provides functionality for staging tags in documents.
+    It will remove documents sections enclosed with "##STAGING##" tags (without quotes).  
+    This is intended to run before the building process of the documentation.
+'''
+
+import os
+from typing import List
+from logger import logger
+
+# Only process files and folders within
+FOLDERS = ('docs_en', 'docs_es')
+ACTIVE_FILE_EXT = ('.md')
+START_PATH = './docs/docs/'
+STAGE_TAG = '## stage ##\n'
+
+def get_stage_tags_positions(list_of_elems, element):
+    '''Returns the indexes of all occurrences of give element in
+    the list- listOfElements'''
+    index_pos_list = []
+    index_pos = 0
+    while True:
+        try:
+            # Search for item in list from indexPos to the end of list
+            index_pos = list_of_elems.index(element, index_pos)
+            # Add the index position in list
+            index_pos_list.append(index_pos)
+            index_pos += 1
+        except ValueError as e:
+            break
+    return index_pos_list
+
+def sanitize_text(stage_tag_positions: List[int], lines: List[str]):
+    '''Returns the text lines that are not enclosed in ## stage ## tags'''
+    stage_tags_pairs = zip(stage_tag_positions[::2], stage_tag_positions[1::2])
+    c = 0
+    for p1, p2 in stage_tags_pairs:
+        del lines[p1:p2+1]
+        c += 1
+    logger.info(f'Total sanitized entries {c}')
+    return lines    
+
+def sanitize_file(root, file_name: str):
+    file = os.path.join(root, file_name)
+    f = open(file, 'r')
+    lines = f.readlines()
+    f.close()
+    stage_tags_linear = get_stage_tags_positions(lines, STAGE_TAG)
+    logger.info(f'Sanitizing file {file}...')
+    if len(stage_tags_linear) == 0:
+        logger.info('No staging sections to remove')
+        return    
+    newText = sanitize_text(stage_tags_linear, lines)
+    f = open(file, 'w')
+    f.writelines(newText)
+    f.close()
+
+def is_markdown_file(filename):
+    return filename.endswith(ACTIVE_FILE_EXT)
+
+def process_files(top_tuple):
+    for topfolder, subfolder, filesintop in top_tuple:
+        """Process files in topfolder first"""
+        for file in filesintop:
+            if is_markdown_file(file):
+                sanitize_file(topfolder, file)
+        """Process subfolders"""
+        for folder in subfolder:
+            folder_walk = os.walk(os.path.join(topfolder, folder))
+            process_files(folder_walk)
+
+root_folders_walk = [ walk for walk in os.walk(START_PATH) if walk[0].endswith(FOLDERS) ]
+process_files(root_folders_walk)

.github/workflows/publish_docs.yml

@@ -0,0 +1,56 @@
+# This workflow will update the online documentation so that it matches the one we have written in mkdocs, it 
+# will be triggered by pushes to master. 
+# It will publish everything by pushing the new site to the gh-pages branch.
+
+name: c4v-py-docs
+
+on:
+  push:
+    branches:
+      - master # for testing, change to master when this work is ready to PR
+jobs:
+  deploy:
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: '3.8'
+          architecture: 'x64'
+
+      - name: Cache dependencies
+        uses: actions/cache@v1
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install -r ./requirements.txt
+
+      - name: Run staging sanitizer
+        run: python ./.github/workflows/ci/stage.py
+
+      - run: |
+          pushd docs
+          mkdocs build
+          popd
+          # cp ./CNAME ./docs/site/CNAME
+          # cp ./.nojekyll ./docs/site/.nojekyll
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+            personal_token: ${{ secrets.DOCS_ACCESS_TOKEN }}
+            publish_dir: ./docs/site
+            publish_branch: docs 
+            commit_message: "Update from commit: ${{ github.sha }} - ${{ github.event.head_commit.message }}"
+            allow_empty_commit: false
+            user_name: devops-c4v
+            user_email: [email protected]
+

README.md

@@ -7,7 +7,7 @@
 > Solving Venezuela pressing matters one commmit at a time
 
 `c4v-py` is a library used to address Venezuela's pressing issues
-using computer and data science.
+using computer and data science. Check the [online documentation](https://code-for-venezuela.github.io/c4v-py/)
 
 - [Installation](#installation)
 - [Development](#development)