Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cbkadal/251docs

251docs
https://github.com/cbkadal/251docs

mkdocs

Last synced: about 1 month ago
JSON representation

251docs

Awesome Lists containing this project

README 

        
# 251docs by CBKADAL!



[ℼ](#idxXXX)


## Table of Content (Toc)

* [Network Address Translation (NAT) Settings](#idx001)

  * [VirtualBox](#idx001)

  * [UTM](#idx001a)

* [GitHub Repo 251docs](#idx002)

* [Debian Packages](#idx003)

* [CLONE Your GitHub Repo on VirtualBox](#idx004)

* [File .gitignore](#idx005)

* [Check Python, Pip, and Venv](#idx006)

* [Python Virtual Environment](#idx007)

* [Activate the Virtual Environment](#idx008)

* [MkDocs and Plugins](#idx009)

* [MkDocs inside folder "docs/"](#idx010)

* [Test from VirtualBox](#idx011)

* [Build the MkDocs site](#idx012)

* [Switch to gh-pages branch](#idx013)

* [Switch to a clean gh-pages branch](#idx014)



[ℼ](#)


## Network Address Translation (NAT) Settings



### VirtualBox



MkDocs is using local port 8000. 

On your VirtualBox, you must redirect/translate the local port 8000 to the host port 4999.

I am already using 5000 for Jekyll and 5001 for Docusaurus.



* VirtualBox Settings

  * Network:Adapter1:

    * Enable Network Adapter

    * Attached to: NAT

    * Port Forwarding:

      * 127.0.0.1:4999 (Host) --- 10.0.2.15:8000 (Guest)








[ℼ](#)



### UTM



MkDocs is using local port 8000. 

On your UTM, you must redirect/translate the local port 8000 to the host port 4999.

I am already using 5000 for Jekyll and 5001 for Docusaurus.



* UTM Settings

  * Network Mode: Emulated VLAN

    * Port Forward: New

      * Protocol: TCP

      * Guest Address: 10.0.2.15

      * Guest Port: 8000

      * Host Address: 127.0.0.1

      * Host Port: 4999

   * SAVE








[ℼ](#)


## GitHub Repo 251docs



* Create a new [GitHub](https://github.com/) repo.

  * New Repository

  * Repository Name: "251docs"

  * Description: "251docs"

  * Public

  * Add README.md

  * Add .gitignore: Python (temporary)

  * Choose any free LICENSE

  * See also 

* Create a GitHub page.

  * (Create branch: gh-pages), apparently will automatically create a GitHub Page?!

  * See also 



[ℼ](#)


## Debian Packages



Make sure the following Debian packages are present in your system.



```

# USER privilege.

export DEBS="

aptitude

build-essential

git

libffi-dev

libssl-dev

python3

python3-dev

python3-pip

python3-venv

sudo

vim

"

time sudo apt-get install $DEBS -y

date



```



[ℼ](#)


## CLONE Your GitHub Repo on VirtualBox

* E.g. repo "251docs/"



```

GITHUB="cbkadal"

REPO="251docs"

git clone [email protected]:$GITHUB/$REPO.git

cd $REPO/



```

* REMEMBER: You are not **CBKADAL**!

* Write your memo on file "README.md".

  * Update/push "README.md" regularly.



[ℼ](#)


### File .gitignore

Copy the following into your .gitignore file:



```

# REVISI: Fri 29 Nov 2024 16:00

# STARTX: Thu 28 Nov 2024 17:00



# Byte-compiled / optimized / DLL files

__pycache__/

*.py[cod]

*$py.class



# Distribution / packaging

.Python

env/

build/

develop-eggs/

dist/

downloads/

eggs/

.eggs/

lib/

lib64/

node_modules/

parts/

sdist/

var/

package*.json

*.egg-info/

.installed.cfg

*.egg



# PyInstaller

*.manifest

*.spec



# Installer logs

pip-log.txt

pip-delete-this-directory.txt

*.log



# Unit test / coverage reports

# Unit test / coverage reports

htmlcov/

.tox/

.coverage

.coverage.*

.cache

nosetests.xml

coverage.xml

*,cover

.hypothesis/



# Virtualenv

venv/

ENV/



# MkDocs documentation

site*/



# Translations

*.mo



# Scrapy stuff:

.scrapy



# PyBuilder

target/



# IPython Notebook

.ipynb_checkpoints



# pyenv

.python-version



# Miscellaneous

.mkdocs-env/

*.tmp

.DS_Store

*.swp



```



[ℼ](#)


## Check Python, Pip, and Venv



```

python --version

pip --version

python -m venv --help



```



[ℼ](#)


## Python Virtual Environment



```

# A centralized ".virtualenvs/" directory

mkdir -pv ~/.virtualenvs/



# Create a Virtual Environment

python3 -m venv ~/.virtualenvs/$(basename $(pwd))



```



[ℼ](#)


## Activate the Virtual Environment

* Before working with "MkDocs", always activate the virtual environment!



```

source ~/.virtualenvs/$(basename $(pwd))/bin/activate



```



* And upgrading PIP inside the Virtual Environment



```

# Upgrade

pip install --upgrade pip

# Check the version

pip --version



```



[ℼ](#)


## Install MkDocs and additional MkDocs plugins



```

pip install mkdocs mkdocs-material



```



* Upgrade, Clean Up, and Verify Version



```

pip install --upgrade pip mkdocs mkdocs-material

pip cache purge

mkdocs --version



```



[ℼ](#)


## MkDocs inside folder "docs/"



```

mkdir -pv docs/

cd docs/

mkdocs new .



```



[ℼ](#)


## Test from VirtualBox



```

mkdocs serve --dev-addr=0.0.0.0:8000



```



* Check it out at "localhost:4999" (HOST)



[ℼ](#)


## Build the MkDocs site

* Build it everytime you want to push it to GitHub Page.



```

mkdocs build



```



[ℼ](#)



### Switch to gh-pages branch



```

git pull origin gh-pages

git checkout gh-pages



```



[ℼ](#)


## Clean gh-pages branch:

* Remove all except move "site/*" one level.



```

git rm -rf .

cp -rv site/* ../

cd ../

git rm -rf docs/

git add .

git commit -m "Deploy MkDocs site"

git push origin gh-pages



```



* Checkit out at , but your are not CBKADAL!






```

REVISI: Fri 29 Nov 2024 17:01

REVISI: Fri 29 Nov 2024 17:00

REVISI: Fri 29 Nov 2024 06:01

REVISI: Fri 29 Nov 2024 00:00

STARTX: Tue 26 Nov 2024 12:00

```