Skip to content

Latest commit

 

History

History
110 lines (100 loc) · 4.04 KB

README.md

File metadata and controls

110 lines (100 loc) · 4.04 KB
Raw

Developer Notebook for Johan Martin

Notes are online at Johan Martin's Development Notes

  • Easier to write things down then trying to remember what you forgot.
  • Working on web development projects is changing rapidly and constantly.
  • Resources are available everywhere but some are outdated and only some help with solving your problem.
  • Easier to review notes on how you solved it last time than googling and going through all the articles again.
  • Too much Googling can lead to a waste of time.
  • Track your development

Tech

  • Notes are written in Markdown
    • Using IA Writer and Microsoft Visual Studio Code to edit the docs.
  • Site generated with MkDocs
    • Deciding factor was the ability to push docs to gh-pages on Github.
    • Essentially free hosting for my document notebook.
  • Notes for setting up notebook in notebook.

Creating Project Documentation

Using MkDocs

  • Uses markdown.
  • Works with github pages.
  • Every project will have their own documentation
    • Styleguide should be included (frontend)
    • Project goals and requirements
    • Notes about development
    • Setup/install instructions
    • Resolution to issues (ongoing FAQ for the projects)
  • Documentation pages stay in gh-pages branch.

Setup

  • Use pipenv
  1. Create project directory and CD into it
  2. Install mkdocs as dev dependency - pipenv install mkdocs --dev
  3. Create mkdocs direcotry - mkdocs new sitedocs
  • sitedocs\docs is where the markdown goes.
  • sitedocs\mkdocs.yml - your table of contents.

Using

  • mkdocs serve - local development server http://localhost:8000
  • mkdocs gh-deploy - build docs and push to gh-pages repo in github after committing.

Config file - mkdocs.yml

site_name: Development Notes for Johan Martin
repo_url: https://github.com/catenare/devnotes
site_description: Notes tracking for developing different apps.
site_author: Johan Martin (http://www.johan-martin.com)
repo_name: 'GitHub'
edit_uri: edit/master/md/
# docs_dir: 'md'
# site_dir: 'docs'
copyright: Johan Martin © 2017
markdown_extensions:
  - pymdownx.tilde
theme: 'material'
pages:
- Home: 'index.md'
- Section:
  - 'Page Sites': 'page.md'
  - Section:
      - sub1: 'sub1.md'
      - sub2: 'sub2.md'

MkDocs Notes

Installing Markdown Extensions

Fixing Issues with MkDocs

  • 404 error for home page/front page - github gh-pages hosting.: Seems like the home page has to point to an "index.md" page for it to work.
  • RuntimeError: Click will abort further execution because Python 3 was configured to use ASCII as encoding for the environment. Consult http://click.pocoo.org/python3/for mitigation steps.
  • Fix with:
    • > export LC_ALL=en_US.UTF-8
    • > export LANG=en_US.UTF-8

Importing docs into Github

  • ghp-import
  • Already being used by MkDocs.
  • Would like to use with Sphinx if I convert my documentation to Sphinx.

Updates

  • Updated notes about WordPress CLI
  • 24 April 2018 - Added API section. PHP, Python, Node.js frameworks related creating APIs. * Added notes about pipenv
  • 25 April 2018 - Added Jupyter notebook with support for TypeScript, JavaScript and Ruby.

Monday 13 April 2020

  • Refactor documents to simplify and make relevant.
  • Topics
    • Cloud
      • AWS
      • Azure
      • Google
        • Firebase
      • Others
        • Cloudinary
    • Web Development
    • Tools
    • Resources