Skip to content

Commit

Permalink
feat: refactor software development documentation structure with new …
Browse files Browse the repository at this point in the history 
…sections on development environment and related tools

lint
  • Loading branch information
@jjjermiah
jjjermiah committed Oct 30, 2024
1 parent 2c958fb commit 05eb33b
Show file tree
Hide file tree
Showing 11 changed files with 124 additions and 40 deletions.
7 changes: 7 additions & 0 deletions docs/software_development/.pages
View file
Original file line number Diff line number Diff line change
@@ -1 +1,8 @@
title: Software Development

nav:
- index.md
- Development_Environment
- Languages
- Version_Control
- Cloud
7 changes: 7 additions & 0 deletions docs/software_development/Development_Environment/.pages
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
nav:
- index.md
- Shells
- Integrated_Development_Environments
- Package_Managers
- CLI_Tools
- Containerization
1 change: 1 addition & 0 deletions docs/software_development/Development_Environment/CLI_Tools/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Command Line Interface (CLI) Tools
0 ...ment_Management/Containerization/index.md → ...ent_Environment/Containerization/index.md
View file
File renamed without changes.
0 ...ntegrated_Development_Environments/.pages → ...ntegrated_Development_Environments/.pages
View file
File renamed without changes.
0 ...egrated_Development_Environments/index.md → ...egrated_Development_Environments/index.md
View file
File renamed without changes.
0 ...ment_Management/Package_Managers/index.md → ...ent_Environment/Package_Managers/index.md
View file
File renamed without changes.
54 changes: 54 additions & 0 deletions docs/software_development/Development_Environment/Shells/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Shells

# What is a Shell?

A shell is a user interface that provides access to the operating system's
services. Typically, it functions as a command-line interface (CLI), where
users can enter commands to perform tasks such as navigating directories,
executing programs, and automating processes with scripts.

## Types of Shells

There are various shells, each offering unique features and catering to
different needs. Some of the most commonly used shells include:

| Shell Name | Description | Platforms |
| -------------- | -------------------------------------------------------------------------------------------- | --------------------- |
| **Bash** | The Bourne Again Shell, commonly used on Unix-based systems. | Unix, Linux, macOS |
| **Zsh** | An enhanced shell with additional features, extending the functionality of the Bourne Shell. | Unix, Linux, macOS |
| **PowerShell** | Task automation and configuration management framework by Microsoft, cross-platform support. | Windows, Linux, macOS |

### TL;DR

Here's a quick comparison of the most popular shells:

| Shell | Best For | Key Strengths |
|-------------|----------------------------------------------|--------------------------------------------------------------------|
| **Bash** | Simplicity, basic scripting, Unix environments | Widely available, easy to use, ideal for general tasks |
| **Zsh** | Customization, advanced features, plugin ecosystem | Highly customizable, rich plugin and theme support, advanced completion |
| **PowerShell** | Cross-platform automation, Windows environments | Object-oriented, powerful scripting, deep Windows integration |

### Comparison Table

Here's a comparison table that highlights the key differences between Bash, PowerShell, and Zsh:

| Feature Category | Bash | PowerShell | Zsh |
|---------------------------|------------------------------------------------------------|------------------------------------------------------------------|---------------------------------------------------------|
| **Features** | | | |
| Simplicity | Simple and beginner-friendly | - | - |
| Portability | Widely available on Unix-like systems | Cross-platform (Windows, Linux, macOS) | - |
| Scripting | Basic scripting support for automation | Advanced scripting with cmdlets and modules | Enhanced scripting over Bash |
| Object-Oriented | - | Works with objects, unlike other text-based shells | - |
| Integration | - | Deep integration with Windows for administrative tasks | - |
| Customizability | - | - | Highly customizable with themes and plugins |
| Completion | - | - | Advanced, programmable completion features |
| Plugins | - | - | Extensive plugin support for extended functionality |
| **User Experience** | | | |
| Default Shell | Default on many Linux distributions and macOS | - | - |
| Prompt | Simple, functional, customizable | Customizable prompt with rich information display | Highly customizable with frameworks like Oh My Zsh |
| Integration with IDEs | - | Integrated with Visual Studio Code | - |
| Themes and Plugins | - | - | Extensive theme and plugin support |
| **Ecosystem and Community** | | | |
| Documentation | Extensive official documentation and community tutorials | Comprehensive official docs by Microsoft | Good official docs and community resources |
| Community | Large and active community with many resources available | Growing community among Windows admins and developers | Active community with strong focus on customization |
| Modules/Plugins | - | Rich set of modules for various administrative tasks | Vibrant plugin and theme ecosystem (e.g., Oh My Zsh) |
27 changes: 27 additions & 0 deletions docs/software_development/Development_Environment/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Development Environment

Think of the development environment as **EVERYTHING** that you need to
develop your project.

This includes:

- What Shell are you using?
- `Bash`
- `PowerShell` for most Windows users
- `Windows Subsystem for Linux` (WSL)
- `Zsh` (commonly installed for macOS users) but can be used on Linux!
- Integrated Development Environments (IDEs)
- VS Code
- PyCharm
- Jupyter Notebook
- etc.
- Package Managers
- Conda/Mamba
- Pixi
- Pip
- npm
- Containerization
- Docker
- Singularity
- Version Control
- etc.
0 docs/software_development/README.md → docs/software_development/index.md
View file
File renamed without changes.
68 changes: 28 additions & 40 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@ repo_url: https://github.com/bhklab/handbook

markdown_extensions:
- toc:
permalink: 🔗
permalink: '#'
permalink_title: Anchor link to this section for reference
toc_depth: 3
- admonition
# From https://squidfunk.github.io/mkdocs-material/reference/code-blocks/
- pymdownx.highlight:
- pymdownx.highlight: # from https://squidfunk.github.io/mkdocs-material/reference/code-blocks/
anchor_linenums: true
line_spans: __span
use_pygments: true
Expand All @@ -20,25 +21,18 @@ markdown_extensions:
- md_in_html

plugins:
- redirects:
- redirects: # handles URL redirects for moved pages
redirect_maps:
"index.md": "General/index.md"
# simplifies configuring page titles and their order
- awesome-pages
# necessary for search functionality to work
- search
# adds authors to pages using git history
- git-authors
# Automatically link to another page's ref
- autorefs:
- awesome-pages # simplifies configuring page titles and their order
- search # necessary for search functionality to work
- git-authors # adds authors to pages using git history
- autorefs: # automatically link to another page's ref
resolve_closest: true
# Adds a date to the bottom of each page
- git-revision-date-localized:
- git-revision-date-localized: # adds a date to the bottom of each page
enable_creation_date: true
# Allows for including Markdown files into another Markdown file
- include-markdown
# Mike not implemented yet
# - mike:
- include-markdown # allows for including Markdown files into another Markdown file
- mike: # mike handles versioned documentation
# # These fields are all optional; the defaults are as below...
# alias_type: symlink
# redirect_template: null
Expand All @@ -64,32 +58,26 @@ theme:
annotation: material/plus-circle
admonition:
features:
- content.code.annotate # Adds annotations to code blocks
- content.code.copy # Adds a copy button to code blocks
- content.code.select # Allows selecting text in code blocks
- content.tabs.link # Links between tabbed content
- content.tooltips # Enables tooltips for additional info
- navigation.indexes # Provides index pages for navigation
- navigation.instant # Instant loading of pages
- navigation.instant.prefetch # Prefetches pages for instant navigation
- navigation.path # Displays path navigation
- navigation.tabs # Adds tab navigation support
- navigation.top # Back to top navigation button
- navigation.tracking # Tracks page navigation statistics
- search.highlight # Highlights search terms
- search.suggest # Suggests search query completions
- toc.follow # Keeps track of the current table of contents entry
- toc.integrate # Integrates the table of contents
- content.code.annotate # adds annotations to code blocks
- content.code.copy # adds a copy button to code blocks
- content.code.select # allows selecting text in code blocks
- content.tabs.link # links between tabbed content
- content.tooltips # enables tooltips for additional info
- navigation.indexes # provides index pages for navigation
- navigation.instant # instant loading of pages
- navigation.instant.prefetch # prefetches pages for instant navigation
- navigation.path # displays path navigation
- navigation.tabs # adds tab navigation support
- navigation.top # back to top navigation button
- navigation.tracking # tracks page navigation statistics
- search.highlight # highlights search terms
- search.suggest # suggests search query completions
- search.share # adds a share button to search results
- toc.follow # keeps track of the current table of contents entry
font:
text: Red Hat Text
code: JetBrains Mono
palette:
# # Palette toggle for automatic mode
# - media: "(prefers-color-scheme")"
# toggle:
# icon: material/brightness-auto
# name: Switch to light mode

# Palette toggle for light mode
- media: "(prefers-color-scheme: light)"
scheme: default
Expand Down

0 comments on commit 05eb33b

Please sign in to comment.