Skip to content

Commit 45c7d45

Browse files
danascapedanascape
committed
feat: Checkout and update docs/ again from 90e66fbc6aeb3fab14ca9165d42d9553122a27aa
Signed-off-by: Saalim Quadri <danascape@gmail.com>
1 parent d2d1208 commit 45c7d45

44 files changed

Lines changed: 17690 additions & 2 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/build_docs.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Build Documentation
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
workflow_dispatch:
9+
10+
jobs:
11+
doc-build:
12+
runs-on: ubuntu-latest
13+
defaults:
14+
run:
15+
shell: bash
16+
working-directory: docs
17+
18+
steps:
19+
- name: Checkout repository
20+
uses: actions/checkout@v4
21+
22+
- name: Install dependencies
23+
run: |
24+
sudo apt-get update
25+
sudo apt-get install -y python3 python3-docutils python3-sphinx
26+
27+
- name: Build documentation
28+
run: |
29+
make html
30+
31+
- name: Deploy to website
32+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
33+
uses: peaceiris/actions-gh-pages@v4
34+
with:
35+
github_token: ${{ secrets.SECRET_TOKEN }}
36+
external_repository: sworkflow-project/website
37+
publish_dir: docs/output/html
38+
allow_empty_commit: true

‎Makefile‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,12 @@ execute-shfmt:
109109
test: check-scripts
110110
@echo "All tests passed"
111111

112+
docs:
113+
$(MAKE) -C docs html
114+
115+
docs-clean:
116+
$(MAKE) -C docs clean
117+
112118
# Distribution targets
113119

114120
dist:
@@ -136,6 +142,8 @@ help:
136142
@echo " make check-scripts Run shellcheck on all scripts"
137143
@echo " make execute-shfmt Format scripts with shfmt"
138144
@echo " make test Run all tests"
145+
@echo " make docs Build documentation"
146+
@echo " make docs-clean Clean documentation build"
139147
@echo ""
140148
@echo "Distribution:"
141149
@echo " make dist Create source tarball"
@@ -144,5 +152,5 @@ help:
144152
.PHONY: install uninstall
145153
.PHONY: _install-system _install-system-bin _install-system-src _install-system-utils _install-system-configs _install-system-man
146154
.PHONY: _uninstall-system _install-user _uninstall-user
147-
.PHONY: check-scripts execute-shfmt test
155+
.PHONY: check-scripts execute-shfmt test docs docs-clean
148156
.PHONY: dist clean help

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,8 @@ The package will be created in the parent directory.
152152
make check-scripts # Run shellcheck
153153
make execute-shfmt # Format scripts
154154
make test # Run all tests
155+
make docs # Build documentation
156+
make docs-clean # Clean documentation build
155157
make help # Show all targets
156158
```
157159

@@ -164,6 +166,7 @@ sworkflow/
164166
├── configs/ # Device configurations
165167
├── utils/ # Python utilities (mkdtboimg.py)
166168
├── man/ # Man pages
169+
├── docs/ # Sphinx documentation
167170
├── debian/ # Debian packaging
168171
├── tests/ # Test scripts
169172
└── Makefile # Build system
@@ -181,6 +184,6 @@ Contributions are welcome! Please check [issues](https://github.com/sworkflow-pr
181184

182185
## Links
183186

184-
- [Documentation](https://github.com/sworkflow-project/Documentation)
187+
- [Documentation](https://github.com/sworkflow-project/sworkflow/docs)
185188
- [Issues](https://github.com/sworkflow-project/issues/issues)
186189
- [Releases](https://github.com/sworkflow-project/sworkflow/releases)

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = output
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/README.md‎

Whitespace-only changes.

‎docs/conf.py‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
import os
14+
import sys
15+
sys.path.insert(0, os.path.abspath('.'))
16+
17+
18+
# -- Project information -----------------------------------------------------
19+
20+
project = 'sworkflow'
21+
copyright = '2019-2024, Saalim Quadri'
22+
author = 'Saalim Quadri'
23+
24+
# The full version, including alpha/beta/rc tags
25+
version = '2.0'
26+
release = '2.0'
27+
28+
# -- General configuration ---------------------------------------------------
29+
30+
# Add any Sphinx extension module names here, as strings. They can be
31+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32+
# ones.
33+
extensions = [
34+
]
35+
36+
# Add any paths that contain templates here, relative to this directory.
37+
templates_path = ['_templates']
38+
39+
# List of patterns, relative to source directory, that match files and
40+
# directories to ignore when looking for source files.
41+
# This pattern also affects html_static_path and html_extra_path.
42+
exclude_patterns = ['output', 'Thumbs.db', '.DS_Store']
43+
44+
45+
# -- Options for HTML output -------------------------------------------------
46+
47+
# The theme to use for HTML and HTML Help pages. See the documentation for
48+
# a list of builtin themes.
49+
#
50+
try:
51+
import sphinx_book_theme
52+
html_theme = 'sphinx_book_theme'
53+
except ImportError:
54+
sys.stdout.write('error: sw will assume the default theme - Alabaster\n')
55+
html_theme = 'alabaster'
56+
57+
# Add any paths that contain custom static files (such as style sheets) here,
58+
# relative to this directory. They are copied after the builtin static files,
59+
# so a file named "default.css" will overwrite the builtin "default.css".
60+
html_static_path = ['_static']

‎docs/content/installorremove.rst‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
========================
2+
Install or Remove ``sw``
3+
========================
4+
5+
Dependencies
6+
------------
7+
8+
**Required:**
9+
10+
- bash (>= 4.0)
11+
- python3
12+
- git
13+
- make
14+
15+
**Recommended (for kernel building):**
16+
17+
- build-essential
18+
- bc, flex, bison
19+
- libssl-dev, libelf-dev
20+
21+
**Optional:**
22+
23+
- clang (for LLVM builds)
24+
- device-tree-compiler (for DTBO)
25+
26+
On Debian/Ubuntu::
27+
28+
sudo apt-get install bash python3 git make build-essential bc flex bison libssl-dev libelf-dev
29+
30+
Install
31+
-------
32+
33+
From Debian Package (Recommended)
34+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
35+
36+
Download the latest ``.deb`` from `Releases <https://github.com/sworkflow-project/sworkflow/releases>`_::
37+
38+
sudo dpkg -i sworkflow_*.deb
39+
sudo apt-get install -f # Install dependencies if needed
40+
41+
From Source (User Install)
42+
~~~~~~~~~~~~~~~~~~~~~~~~~~
43+
44+
Installs to ``~/.local/`` - no root required::
45+
46+
git clone https://github.com/sworkflow-project/sworkflow.git
47+
cd sworkflow
48+
make install
49+
50+
Ensure ``~/.local/bin`` is in your PATH::
51+
52+
export PATH="$HOME/.local/bin:$PATH"
53+
54+
Add this line to your ``~/.bashrc`` to make it permanent.
55+
56+
From Source (System-wide)
57+
~~~~~~~~~~~~~~~~~~~~~~~~~
58+
59+
Installs to ``/usr/``::
60+
61+
git clone https://github.com/sworkflow-project/sworkflow.git
62+
cd sworkflow
63+
sudo make install
64+
65+
Verify Installation
66+
~~~~~~~~~~~~~~~~~~~
67+
68+
To check if the installation was successful::
69+
70+
sw version
71+
sw help
72+
73+
Uninstall
74+
---------
75+
76+
User Installation
77+
~~~~~~~~~~~~~~~~~
78+
79+
::
80+
81+
make uninstall
82+
83+
System Installation
84+
~~~~~~~~~~~~~~~~~~~
85+
86+
::
87+
88+
sudo make uninstall
89+
90+
Debian Package
91+
~~~~~~~~~~~~~~
92+
93+
::
94+
95+
sudo apt-get remove sworkflow

‎docs/content/project_structure.rst‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
=================
2+
Project Structure
3+
=================
4+
5+
Directory Layout
6+
----------------
7+
8+
::
9+
10+
sworkflow/
11+
├── sw # Main executable
12+
├── src/ # Source modules
13+
│ ├── build.sh # Kernel build logic
14+
│ ├── build_vars.sh # Build variables
15+
│ ├── init.sh # Config generation
16+
│ ├── help.sh # Help command
17+
│ ├── version.sh # Version command
18+
│ ├── sw_functions.sh # Utility functions
19+
│ ├── sw_color.sh # Terminal colors
20+
│ └── sw_package.sh # Packaging (WIP)
21+
├── configs/ # Device configurations
22+
├── utils/ # Python utilities
23+
│ └── mkdtboimg.py # DTBO image creator
24+
├── man/ # Man pages
25+
│ └── sw.1 # Main man page
26+
├── debian/ # Debian packaging
27+
├── docs/ # Sphinx documentation
28+
├── tests/ # Test scripts
29+
├── Makefile # Build system
30+
├── setup.sh # Legacy installer
31+
└── README.md # Project readme
32+
33+
Source Modules
34+
--------------
35+
36+
**sw**
37+
Main entry point. Handles command routing and path detection.
38+
39+
**src/build.sh**
40+
Core kernel build logic. Handles:
41+
42+
- Config loading and validation
43+
- Cross-compiler setup
44+
- Kernel compilation with make
45+
- Module installation
46+
- DTBO generation
47+
- AnyKernel3 packaging
48+
49+
**src/init.sh**
50+
Interactive configuration generator. Creates device-specific
51+
config files with user input.
52+
53+
**src/sw_functions.sh**
54+
Shared utility functions:
55+
56+
- ``is_kernel_root()`` - Check if directory is a kernel tree
57+
- ``is_kernel_image_present()`` - Check for compiled kernel
58+
- ``log_info()``, ``log_error()`` - Logging functions
59+
60+
**src/sw_color.sh**
61+
Terminal color definitions for output formatting.
62+
63+
Installation Paths
64+
------------------
65+
66+
**System Installation** (``sudo make install``)::
67+
68+
/usr/bin/sw # Executable
69+
/usr/share/sworkflow/src/ # Source modules
70+
/usr/share/sworkflow/utils/ # Python utilities
71+
/etc/sworkflow/ # Device configs
72+
/usr/share/man/man1/sw.1 # Man page
73+
74+
**User Installation** (``make install``)::
75+
76+
~/.local/bin/sw # Executable
77+
~/.local/sw/src/ # Source modules
78+
~/.local/sw/utils/ # Python utilities
79+
~/.local/sw/configs/ # Device configs
80+
81+
Configuration Files
82+
-------------------
83+
84+
Device configurations are shell scripts named ``sworkflow.<device>.config``.
85+
86+
They are searched in order:
87+
88+
1. ``/etc/sworkflow/`` (system)
89+
2. ``~/.local/sw/configs/`` (user)
90+
3. Current directory
91+
4. ``./configs/`` subdirectory
92+
93+
See ``configs/sworkflow_template.config`` for available variables.

‎docs/dependencies/debian.dependencies‎

Whitespace-only changes.

‎docs/dependencies/pip.dependencies‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
sphinx-book-theme

0 commit comments

Comments
 (0)