mirror of
https://github.com/bluxmit/alnoda-workspaces.git
synced 2024-09-30 09:16:14 +13:00
mkdocs magicspace readme
This commit is contained in:
parent
56047c28d0
commit
3909b64721
6 changed files with 121 additions and 62 deletions
|
@ -185,7 +185,7 @@ The most general workspace - is [`Ubuntu-workspace`](./workspaces/ubuntu-workspa
|
||||||
in order to run multiple processes, adds cron, zsh, and other applications that will be used in most workspaces.
|
in order to run multiple processes, adds cron, zsh, and other applications that will be used in most workspaces.
|
||||||
|
|
||||||
Other general workspaces are the [`Base-Workspace`](./workspaces/base-workspace/README.md), which adds several browser-based applications,
|
Other general workspaces are the [`Base-Workspace`](./workspaces/base-workspace/README.md), which adds several browser-based applications,
|
||||||
like task scheduler, file browser, documentation framework and workspace own page. [`Workspace-in-docker`](./workspaces/workspace-in-docker/README.md)
|
like task scheduler, file browser, documentation framework and workspace own UI. [`Workspace-in-docker`](./workspaces/workspace-in-docker/README.md)
|
||||||
adds [Eclipse Theia](https://theia-ide.org/) to the Base-Workspace. Theia - is an open-source browser-based VS-Code version, making
|
adds [Eclipse Theia](https://theia-ide.org/) to the Base-Workspace. Theia - is an open-source browser-based VS-Code version, making
|
||||||
Workspace-in-docker to be a general base workspace, to be used in order to create workspaces for specific tasks (like Python workspace, or
|
Workspace-in-docker to be a general base workspace, to be used in order to create workspaces for specific tasks (like Python workspace, or
|
||||||
Ansible workspace).
|
Ansible workspace).
|
||||||
|
|
|
@ -4,7 +4,7 @@ General-purpose dockerized workspace - an environment fully isolated inside a do
|
||||||
to file or restored, pushed to docker registry, started on a cloud server.
|
to file or restored, pushed to docker registry, started on a cloud server.
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="./img/codeserver-wid-collage.png" alt="Collage">
|
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-wid-collage.png" alt="Collage">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
#### Try it out
|
#### Try it out
|
||||||
|
@ -46,7 +46,7 @@ The Workspace contains browser-based Visual Studio Code, and several browser-bas
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="./img/codeserver-wid-demo.gif" alt="WID demo" width="900">
|
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-wid-demo.gif" alt="WID demo" width="900">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
**Tools with UI**
|
**Tools with UI**
|
||||||
|
@ -91,7 +91,7 @@ The IDE is already configured to make code highlighting for many programming lan
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="./img/codeserver-demo.gif" alt="Code-server demo" width="900">
|
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-demo.gif" alt="Code-server demo" width="900">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
@ -217,7 +217,7 @@ Open [localhost:8020](http://localhost:8020), and from there open other applicat
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="./img/codeserver-ui.png" alt="codeserver-ui.png" width="750">
|
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-ui.png" alt="codeserver-ui.png" width="750">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
The rest of the ports from the port range can be used in order to expose optional applications, or applications you might
|
The rest of the ports from the port range can be used in order to expose optional applications, or applications you might
|
||||||
|
@ -298,7 +298,7 @@ use utility `/home/abc/utils/remote.py` to generate create docker-compose projec
|
||||||
After the command is executed, you will see folder `/home/abc/utils/remote` is created. Download it out from the workspace to the local environment using the Filebrowser:
|
After the command is executed, you will see folder `/home/abc/utils/remote` is created. Download it out from the workspace to the local environment using the Filebrowser:
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="./img/codeserver-remote-gen.gif" alt="generate-remote.gif" width="750">
|
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-remote-gen.gif" alt="generate-remote.gif" width="750">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
. Copy this folder to the remote server where you want to launch the Python workspace.
|
. Copy this folder to the remote server where you want to launch the Python workspace.
|
||||||
|
@ -594,7 +594,7 @@ the new page has appeared in your Workspace UI - it has live reload, and you don
|
||||||
|
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="./img/codeserver-docs.gif" alt="workspace-docs" width="900">
|
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-docs.gif" alt="workspace-docs" width="900">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
You can easily build beautiful static website from this documentation
|
You can easily build beautiful static website from this documentation
|
||||||
|
|
|
@ -5,27 +5,33 @@
|
||||||
MkDocs-MagicSpace is an all-in-one tool, carefully crafted to make the development of gorgeous documentation
|
MkDocs-MagicSpace is an all-in-one tool, carefully crafted to make the development of gorgeous documentation
|
||||||
websites like [**this one**](https://mkdocs-magicspace.alnoda.org/) as easy as possible.
|
websites like [**this one**](https://mkdocs-magicspace.alnoda.org/) as easy as possible.
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<img src="./img/mkdocs-collage.png" alt="Collage">
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
Try it out:
|
Try it out:
|
||||||
|
|
||||||
```
|
```
|
||||||
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/mkdocs-magicspace
|
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/mkdocs-magicspace
|
||||||
```
|
```
|
||||||
|
|
||||||
and open [http://localhost:8020] in browser
|
and open [localhost:8020](http://localhost:8020) in browser
|
||||||
|
|
||||||
## Contents
|
## Contents
|
||||||
|
|
||||||
|
* [Why documentation websites with MkDocs](#why-documentation-websites-with-mkdocs)
|
||||||
|
* [About](#about)
|
||||||
|
* [MkDocs features](#mkdocs-features)
|
||||||
* [Use-cases](#use-cases)
|
* [Use-cases](#use-cases)
|
||||||
* [Why documentation websites](#why-documentation-websites)
|
|
||||||
* [Features](#features)
|
|
||||||
* [The technology behind](#the-technology-behind)
|
|
||||||
* [Launch Workspace](#launch-workspace)
|
* [Launch Workspace](#launch-workspace)
|
||||||
* [Workspace terminal](#workspace-terminal)
|
* [Workspace terminal](#workspace-terminal)
|
||||||
* [Multiple workspaces](#multiple-workspaces)
|
* [Multiple workspaces](#multiple-workspaces)
|
||||||
* [Open more ports](#open-more-ports)
|
* [Open more ports](#open-more-ports)
|
||||||
* [Docker in docker](#docker-in-docker)
|
* [Docker in docker](#docker-in-docker)
|
||||||
* [Run on remote server](#run-on-remote-server)
|
* [Run on remote server](#run-on-remote-server)
|
||||||
* [Use Workspace](#use-workspace)
|
* [Use Workspace](#use-workspace)
|
||||||
|
* [Create MkDocs website](#create-mkdocs-website)
|
||||||
* [Install applications](#install-applications)
|
* [Install applications](#install-applications)
|
||||||
* [Schedule jobs with Cron](#schedule-jobs-with-cron)
|
* [Schedule jobs with Cron](#schedule-jobs-with-cron)
|
||||||
* [Python](#python)
|
* [Python](#python)
|
||||||
|
@ -39,30 +45,9 @@ and open [http://localhost:8020] in browser
|
||||||
* [Move workspace to the cloud](#move-workspace-to-the-cloud)
|
* [Move workspace to the cloud](#move-workspace-to-the-cloud)
|
||||||
|
|
||||||
|
|
||||||
## Use-cases
|
## Why documentation websites with MkDocs
|
||||||
|
|
||||||
With the help of MkDocs-MagicSpace you can develop, build and serve the following kinds of websites:
|
*Why create separate documentation websites? And if so, why MkDocs?*
|
||||||
|
|
||||||
1. Awesome looking docs for your open-source project. Use HTML & CSS to create front page and markdown for doc pages.
|
|
||||||
|
|
||||||
2. User manuals and API docs. While enterprise docs are for internal use, create great-looking API websites for your users, and manuals for your customers.
|
|
||||||
|
|
||||||
1. Enterprise documentation websites that unite numerous git repositories into one documentation project.
|
|
||||||
|
|
||||||
4. Tutorials and training websites. Do you have a lot of experience in something? Share it with the world.
|
|
||||||
MkDocs-MagicSpace helps you to highlight the code in many programming languages, write complex mathematical formulas,
|
|
||||||
[draw diagrams]((https://mermaid-js.github.io/mermaid/#/)) and so much more!
|
|
||||||
|
|
||||||
5. With MkDocs-MagicSpace you can also create books, booklets, and brochures as .pdf files.
|
|
||||||
|
|
||||||
One of the most convenient features of the MkDocs-MagicSpace - is that it is a workspace in docker.
|
|
||||||
You use it on your local machine, you can run it on the remote server and collaborate with your colleagues,
|
|
||||||
you can give it to your peer as a whole. And you can use it to serve your docs from any server, no matter
|
|
||||||
if it is public or inside the company's VPN.
|
|
||||||
|
|
||||||
## Why documentation websites
|
|
||||||
|
|
||||||
*Why create separate documentation websites? Why not just write Git readme files?*
|
|
||||||
|
|
||||||
- MkDocs website with beautiful themes looks much better than any readme file. The resulting documentation website looks professional and awesome.
|
- MkDocs website with beautiful themes looks much better than any readme file. The resulting documentation website looks professional and awesome.
|
||||||
- MkDocs adds text search to your documentation website.
|
- MkDocs adds text search to your documentation website.
|
||||||
|
@ -72,22 +57,18 @@ if it is public or inside the company's VPN.
|
||||||
can create a unified documentation website from multiple repositories in Github, GitLab, Bitbucket.
|
can create a unified documentation website from multiple repositories in Github, GitLab, Bitbucket.
|
||||||
- You can add such features as Google Analytics, multi-language localization.
|
- You can add such features as Google Analytics, multi-language localization.
|
||||||
|
|
||||||
*And what about Confluent?*
|
|
||||||
|
|
||||||
The approach of having docs in different places (Git repositories, Confluent, Wiki, etc.) has serious drawbacks. It creates chaos, and documentation inevitably diverges with time.
|
## About
|
||||||
And you never know where to look for the information you need.
|
|
||||||
|
|
||||||
The best docs live together with the code. With MkDocs-MagicSpace you can follow this practice with ease, build a documentation website
|
The Workspace contains browser-based Visual Studio Code, and several browser-based tools that make it more convenient to work from inside a docker container.
|
||||||
from one or many git repositories, include readme files that live close to the code. You can have a build process that even creates
|
|
||||||
auto-documentation directly from the code.
|
|
||||||
|
|
||||||
## Features
|
<div align="center" style="font-style: italic;">
|
||||||
|
Demo: MkDocs-MagicSpace
|
||||||
|
</div>
|
||||||
|
|
||||||
MkDocs-MagicSpace has [**MkDocs**](https://squidfunk.github.io/mkdocs-material/) installed with a collection of extensions and plugins
|
<p align="center">
|
||||||
that bring MkDocs to the next level.
|
<img src="./img/mkdocs-magicspace-demo.gif" alt="Magicspace demo" width="900">
|
||||||
|
</p>
|
||||||
MkDocs-MagicSpace is an extension of the [workspace-in-docker](https://github.com/Alnoda/workspaces-in-docker/blob/main/workspaces/workspace-in-docker/README.md)
|
|
||||||
and has all its features:
|
|
||||||
|
|
||||||
- **Workspace UI** - launch all workspace tools from one place.
|
- **Workspace UI** - launch all workspace tools from one place.
|
||||||
- [**Eclipse Theia**](https://theia-ide.org/docs/) - open source version of popular Visual Studio Code IDE. Theia is trully open-source, has
|
- [**Eclipse Theia**](https://theia-ide.org/docs/) - open source version of popular Visual Studio Code IDE. Theia is trully open-source, has
|
||||||
|
@ -99,10 +80,23 @@ VS-Code extensions and works in browser. This means it can run inside a docker c
|
||||||
- [**Midnight Commander**](https://midnight-commander.org/) - Feature rich visual file manager with internal text viewer and editor.
|
- [**Midnight Commander**](https://midnight-commander.org/) - Feature rich visual file manager with internal text viewer and editor.
|
||||||
- [**Process Monitor**](https://htop.dev/) - Monitor running process and resource utilization.
|
- [**Process Monitor**](https://htop.dev/) - Monitor running process and resource utilization.
|
||||||
|
|
||||||
Built on top of Base-workspace and Ubuntu-workspace, this workspace gets all the features those workspaces have.
|
**Other:**
|
||||||
In particular, workspace-in-docker provides excellent experience when working directly in the terminal, and has docker-in-docker.
|
- Docker in docker
|
||||||
|
- [Zsh](https://www.zsh.org/), [Oh my Zsh](https://ohmyz.sh/)
|
||||||
|
- Python 3, Pip
|
||||||
|
- Node/nodeenv
|
||||||
|
- git, git-flow
|
||||||
|
- curl, wget, telnet, jq,
|
||||||
|
- nano, vim, mc, ncdu, htop
|
||||||
|
- supervisord
|
||||||
|
- cron
|
||||||
|
|
||||||
#### The technology behind
|
Built on top of [Workspace-in-docker](https://github.com/Alnoda/workspaces-in-docker/blob/main/workspaces/workspace-in-docker/README.md),
|
||||||
|
[Base-workspace](https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/base-workspace/README.md), and
|
||||||
|
[Ubuntu-workspace](https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/ubuntu-workspace/README.md),
|
||||||
|
this workspace gets all the features those workspaces have.
|
||||||
|
|
||||||
|
#### MkDocs features
|
||||||
|
|
||||||
MkDocs-MagicSpace in its essense is all about [**MkDocs**](https://www.mkdocs.org/) - a fast, simple and downright gorgeous static site generator that's geared towards
|
MkDocs-MagicSpace in its essense is all about [**MkDocs**](https://www.mkdocs.org/) - a fast, simple and downright gorgeous static site generator that's geared towards
|
||||||
building project documentation.
|
building project documentation.
|
||||||
|
@ -125,6 +119,29 @@ MkDocs-MagicSpace has lots of packages and extensions already installed:
|
||||||
|
|
||||||
**(The complete list of installed packages - /home/abc/installed-python-packages/mkdocs-requirements.txt)**
|
**(The complete list of installed packages - /home/abc/installed-python-packages/mkdocs-requirements.txt)**
|
||||||
|
|
||||||
|
## Use-cases
|
||||||
|
|
||||||
|
This workspace has many tools and dependencies, configuring it from scratch will cost you a lot of time.
|
||||||
|
|
||||||
|
With the help of MkDocs-MagicSpace you can develop, build and serve the following kinds of websites:
|
||||||
|
|
||||||
|
1. Awesome looking docs for your open-source project. Use HTML & CSS to create front page and markdown for doc pages.
|
||||||
|
|
||||||
|
2. User manuals and API docs. While enterprise docs are for internal use, create great-looking API websites for your users, and manuals for your customers.
|
||||||
|
|
||||||
|
1. Enterprise documentation websites that unite numerous git repositories into one documentation project.
|
||||||
|
|
||||||
|
4. Tutorials and training websites. Do you have a lot of experience in something? Share it with the world.
|
||||||
|
MkDocs-MagicSpace helps you to highlight the code in many programming languages, write complex mathematical formulas,
|
||||||
|
[draw diagrams]((https://mermaid-js.github.io/mermaid/#/)) and so much more!
|
||||||
|
|
||||||
|
5. With MkDocs-MagicSpace you can also create books, booklets, and brochures as .pdf files.
|
||||||
|
|
||||||
|
One of the most convenient features of the MkDocs-MagicSpace - is that it is a workspace in docker.
|
||||||
|
You use it on your local machine, you can run it on the remote server and collaborate with your colleagues,
|
||||||
|
you can give it to your peer as a whole. And you can use it to serve your docs from any server, no matter
|
||||||
|
if it is public or inside the company's VPN.
|
||||||
|
|
||||||
## Launch Workspace
|
## Launch Workspace
|
||||||
|
|
||||||
Workspaces - are merely docker containers, that's why managing workspaces is easy and intuitive - it is enough to know only docker commands,
|
Workspaces - are merely docker containers, that's why managing workspaces is easy and intuitive - it is enough to know only docker commands,
|
||||||
|
@ -279,23 +296,65 @@ use utility `/home/abc/utils/remote.py` to generate create docker-compose projec
|
||||||
|
|
||||||
**NOTE:** you have to specify the correct host (IP of the server you want to run the workspace on), and user and password of your choice.
|
**NOTE:** you have to specify the correct host (IP of the server you want to run the workspace on), and user and password of your choice.
|
||||||
|
|
||||||
You see folder `/home/abc/utils/remote` is created. Copy this folder to the remote server (any location). Ssh to the server, cd into
|
After the command is executed, you will see folder `/home/abc/utils/remote` is created. Download it out from the workspace to the local environment using the Filebrowser:
|
||||||
the directory you copied and execute `docker-compose up -d`.
|
|
||||||
|
<p align="center">
|
||||||
|
<img src="./img/mkdocs-remote.gif" alt="mkdocs-remote.gif" width="750">
|
||||||
|
</p>
|
||||||
|
|
||||||
|
. Copy this folder to the remote server where you want to launch the Python workspace.
|
||||||
|
You can use cyberduck or [scp](https://kb.iu.edu/d/agye). ssh to the server, cd to the directory you copied and execute
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker-compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
That's it, you workspace is running securely on the remote server, using
|
That's it, you workspace is running securely on the remote server, using
|
||||||
self-signed TLS certificates for encrypted https communication between you laptop and the remote workspace,
|
self-signed TLS certificates for encrypted https communication between you laptop and the remote workspace, and authentication is added.
|
||||||
and authentication is added.
|
|
||||||
|
**NOTE:** The HTTPS is with self-signed certificate, and your browser will show a warning, asking you to accept the risk
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ubuntu-workspace/img/accept-risks.png" alt="accept-risk" width="750">
|
||||||
|
</p>
|
||||||
|
|
||||||
|
After you accept the risk, authentication window will appear asking you the user and password, that you have set as<ANY_USER_NAME>, <ANY_USER_PASSWORD>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ubuntu-workspace/img/auth.png" alt="auth" width="750">
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
## Use Workspace
|
## Use Workspace
|
||||||
|
|
||||||
Among the common actions you'd do in the workspace are
|
### Create MkDocs website
|
||||||
|
|
||||||
|
[MkDocs](https://www.mkdocs.org/) is very powerful. Even more powerful it becomes with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
|
||||||
|
But this workspace takes it to the space by having tons of Markdown plugins carefully selected, configured, and set up. It would be impossible to
|
||||||
|
demonstrate all of the advanced Markdown features in the Readme file, simply because standard engines that render Markdown do not support the
|
||||||
|
advanced features.
|
||||||
|
|
||||||
|
We have prepared extended Markdown tutorials, so that you don't need to search in the Internet for docs of every Markdown plugin.
|
||||||
|
They are all in one place:
|
||||||
|
|
||||||
|
* [Intro](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/intro/)
|
||||||
|
* [Basics](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/basics/)
|
||||||
|
* [Hack the markdown](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/hack-markdown/)
|
||||||
|
* [Improve readability with tabs, lists and footnotes](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/improve-readability/)
|
||||||
|
* [Create tables](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/tables/)
|
||||||
|
* [Highlight with blockquotes and admonitions](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/highlight-what-matters/)
|
||||||
|
* [Make it classy with emoji, icons and more](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/classy-markdown/)
|
||||||
|
* [Make images awesome](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/images/)
|
||||||
|
* [Add the code](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/add-the-code/)
|
||||||
|
* [Write formulas](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/formulas/)
|
||||||
|
* [Draw diagrams](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/diagrams/)
|
||||||
|
* [Use templates](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/templates-macros/)
|
||||||
|
|
||||||
|
In addition you can find here tutorials how to build and deploy your website in just couple of clicks
|
||||||
|
* [Build website](https://mkdocs-magicspace.alnoda.org/tutorials/get-online/build-workspace/)
|
||||||
|
* [Publish on GitHub Pages](https://mkdocs-magicspace.alnoda.org/tutorials/get-online/github-pages/)
|
||||||
|
|
||||||
|
|
||||||
- installation of new applications and runtimes
|
|
||||||
- edit files, write code, scripts
|
|
||||||
- build, compile and execute code
|
|
||||||
- start/stop applications and services
|
|
||||||
- schedule tasks and scripts
|
|
||||||
- process data
|
|
||||||
|
|
||||||
### Install applications
|
### Install applications
|
||||||
|
|
||||||
|
|
BIN
workspaces/mkdocs-magicspace/img/mkdocs-collage.png
Normal file
BIN
workspaces/mkdocs-magicspace/img/mkdocs-collage.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 1.4 MiB |
BIN
workspaces/mkdocs-magicspace/img/mkdocs-magicspace-demo.gif
Normal file
BIN
workspaces/mkdocs-magicspace/img/mkdocs-magicspace-demo.gif
Normal file
Binary file not shown.
After Width: | Height: | Size: 25 MiB |
BIN
workspaces/mkdocs-magicspace/img/mkdocs-remote.gif
Normal file
BIN
workspaces/mkdocs-magicspace/img/mkdocs-remote.gif
Normal file
Binary file not shown.
After Width: | Height: | Size: 3.6 MiB |
Loading…
Reference in a new issue