State of the art, project management and documentation¶
1. Objective¶
weekly assignment
- Build a documentation website describing you and your motivation for the textile-academy, including your previous work
- Upload the documentation to your project page on class.textile-academy.org
- Add references and research based on the topic of your interest
- Learn how to upload images, videos, references and how to use Markdown and Gitlab
- Learn to resize and “optimize for web” images, videos and files
- Learn about the fab lab processes, booking system, usage, machine demos, tools and safety rules
2. Documentation Process¶
As task for Week 1 is to setup the project management pipeline for rest of the course. And explore the tools for documenting and maintaining the website using Visual Studio Code (VS Code) and the GitLab Web IDE.
The goal is to become comfortable with:
- Navigating VS Code
- Using the terminal
- Understanding Git
- Working with GitLab repositories
- Editing a project through GitLab Web IDE
- Committing and pushing changes
- Building a documentation website with Markdown
2.1 Installing VS code¶
Installing VS Code
Download and install VS Code from the official website:
https://code.visualstudio.com/
After installation, open VS Code.
Installing git¶
VS Code has built-in Git integration, but Git itself must be installed separately on the computer.
Download Git from: https://git-scm.com/downloads
Once installed, Use terminal to confirm by using command ''git --version''
Install Python¶
Download Python from Python.org. During installation, Make sure to check the following option-
Add Python to PATH
Once the installation is finished, similar to git, Open a new VS Code terminal and check Python ''py --version''.
Create SSH key¶
A Gitlab SSH key is a secure credential used to authenticate with GitHub via the SSH (Secure Shell) protocol. Here's the official guide to create the SSH key pair by GitLab Docs.
Clone the GitLab repo to local¶
Open the VS Code terminal.
Move to the location where you want to store your project and clone the repository using following command replacing the URL with the SSH URL you copied from GitLab. ''git clone git@gitlab.com:username/project.git''
ssh screenshot here
Git downloads the repository and creates a local project directory.
Install Zensical¶
Zensical is a modern static website generator to help users build websites from Markdown files quickly and efficiently. Once the repo is cloned Zensical can be directly installed inside the repo. For this one approach is to use Python virtual environment(''venv'') so that zensical and it's dependancies can be kept isolated.
From the root of the cloned repository, run ''python -m venv .venv'' And activate it by ''.venv\Scripts\activate'' Now, with (.venv) activated run ''pip install zensical'' Confirm the zensical install by ''zensical --version''
Zensical starts a local development server and watches your documentation for changes, for that run ''zensical serve''. You can access the local website at http://localhost:8000 .
Commiting changes and Publishing the website¶
Once all the necessary changes are made, stage the changes in source control panel in VS code. Check and confirm the changes using the dropdown to view individual changes. Once confirmed, write a update message for the changes and click Commit and Push to 'main'