explicode 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +24 -53
- package/package.json +10 -1
package/README.md
CHANGED
|
@@ -2,40 +2,33 @@
|
|
|
2
2
|
|
|
3
3
|
> Turn your codebase into documentation.
|
|
4
4
|
|
|
5
|
-
**Explicode** lets you write rich Markdown documentation directly inside your code comments, turning a single source file into both runnable code and beautifully rendered documentation.
|
|
5
|
+
**Explicode** is an open-source project that lets you write rich Markdown documentation directly inside your code comments, turning a single source file into both runnable code and beautifully rendered documentation. The VS Code extension provides live previews of your documentation right inside your IDE. Additionally, the `npm` package can convert supported source files into `.md` Markdown via the terminal or generate a GitHub Pages-ready `docs/` folder.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
[](https://marketplace.visualstudio.com/items?itemName=Explicode.explicode)[](https://marketplace.visualstudio.com/items?itemName=Explicode.explicode)
|
|
8
8
|
|
|
9
|
-
[](https://marketplace.visualstudio.com/items?itemName=Explicode.explicode)
|
|
10
|
-
[](https://marketplace.visualstudio.com/items?itemName=Explicode.explicode)
|
|
11
9
|
[](https://github.com/benatfroemming/explicode)
|
|
12
10
|
|
|
13
|
-
|
|
11
|
+
## How It Works
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
Explicode lets you write Markdown directly inside your source code comments. The rules for each language are:
|
|
16
14
|
|
|
17
|
-
|
|
15
|
+
- **Python** — Triple-quoted docstrings (`""" ... """` or `''' ... '''`) placed in the normal docstring position are treated as prose. All other code is rendered as code blocks.
|
|
16
|
+
- **C-style languages** — Block comments (`/* ... */`) are treated as prose, while the rest of the code is rendered as code blocks.
|
|
17
|
+
- **Markdown files** — Passed through directly without changes.
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
npx explicode build
|
|
21
|
-
npx explicode build --dark
|
|
22
|
-
npx explicode convert <file>
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
---
|
|
19
|
+
**Supported Languages:** Python, JavaScript, TypeScript, JSX, TSX, Java, C, C++, C#, CUDA, Rust, Go, Swift, Kotlin, Scala, Dart, PHP, Objective-C, SQL, Markdown
|
|
26
20
|
|
|
27
21
|
## Commands
|
|
28
22
|
|
|
29
23
|
### `convert`
|
|
30
24
|
|
|
31
|
-
Converts a single file to Markdown
|
|
25
|
+
Converts a single file to Markdown.
|
|
32
26
|
|
|
33
27
|
```bash
|
|
34
|
-
npx explicode convert
|
|
28
|
+
npx explicode convert <file> # usage
|
|
29
|
+
npx explicode convert src/utils.py # example: outputs `src/utils.py.md` alongside the original file
|
|
35
30
|
```
|
|
36
31
|
|
|
37
|
-
Outputs `src/utils.py.md` alongside the original file.
|
|
38
|
-
|
|
39
32
|
### `build`
|
|
40
33
|
|
|
41
34
|
Scans the current directory and generates a `docs/` folder.
|
|
@@ -50,32 +43,14 @@ npx explicode build --dark # dark theme
|
|
|
50
43
|
- Wraps code in syntax-highlighted fenced blocks
|
|
51
44
|
- Copies your `README.md` as the docs home page
|
|
52
45
|
- Generates a `_sidebar.md` with your full file tree
|
|
53
|
-
- Writes an `index.html` ready for Docsify + GitHub Pages
|
|
46
|
+
- Writes an `index.html` ready for [Docsify](https://docsify.js.org/#/) + [GitHub Pages](https://docs.github.com/pages)
|
|
54
47
|
- Adds "View on GitHub" source links if a GitHub remote is detected
|
|
55
48
|
|
|
56
49
|
**Skipped directories:** `node_modules`, `.git`, `dist`, `build`, `out`, `docs`, `.next`, `.nuxt`, `.cache`, `.venv`, `venv`, `__pycache__`
|
|
57
50
|
|
|
58
|
-
---
|
|
59
|
-
|
|
60
|
-
## Supported Languages
|
|
61
|
-
|
|
62
|
-
Python, JavaScript, TypeScript, JSX, TSX, Java, C, C++, C#, CUDA, Rust, Go, Swift, Kotlin, Scala, Dart, PHP, Objective-C, SQL, Markdown
|
|
63
|
-
|
|
64
|
-
---
|
|
65
|
-
|
|
66
|
-
## How It Works
|
|
67
|
-
|
|
68
|
-
- **Python** — Triple-quoted docstrings (`"""` / `'''`) in docstring position become prose. Everything else becomes a code block.
|
|
69
|
-
- **C-style languages** — Block comments (`/* ... */`) become prose. Everything else becomes a code block.
|
|
70
|
-
- **Markdown** — Passed through as-is.
|
|
71
|
-
|
|
72
|
-
Consecutive segments of the same type are merged, producing clean alternating prose/code sections rather than fragmented blocks.
|
|
73
|
-
|
|
74
|
-
---
|
|
75
|
-
|
|
76
51
|
## GitHub Pages
|
|
77
52
|
|
|
78
|
-
After running `build`, push the `docs/` folder
|
|
53
|
+
After running `npx explicode build`, push your changes including the generated `docs/` folder to your repository. Then, in your repository settings, enable GitHub Pages using the `docs/` folder as the source. Your site will be live at:
|
|
79
54
|
|
|
80
55
|
```
|
|
81
56
|
https://<user>.github.io/<repo>
|
|
@@ -83,23 +58,23 @@ https://<user>.github.io/<repo>
|
|
|
83
58
|
|
|
84
59
|
### Automatic Deployment with GitHub Actions
|
|
85
60
|
|
|
86
|
-
Add the following file to your repository to automatically build and deploy docs on every push:
|
|
61
|
+
Add the following workflow file to your repository to automatically build and deploy your Explicode docs on every push:
|
|
87
62
|
|
|
88
|
-
`.github/workflows/<
|
|
63
|
+
`.github/workflows/<workflow_name>.yml`
|
|
89
64
|
|
|
90
65
|
```yml
|
|
91
|
-
name: Deploy Docs
|
|
66
|
+
name: Deploy Explicode Docs
|
|
92
67
|
|
|
93
68
|
on:
|
|
94
69
|
push:
|
|
95
|
-
branches: [main]
|
|
96
|
-
workflow_dispatch:
|
|
70
|
+
branches: [main] # replace with your desired branch
|
|
71
|
+
workflow_dispatch: # lets users trigger it manually from GitHub UI
|
|
97
72
|
|
|
98
73
|
jobs:
|
|
99
74
|
deploy:
|
|
100
75
|
runs-on: ubuntu-latest
|
|
101
76
|
permissions:
|
|
102
|
-
contents: write
|
|
77
|
+
contents: write # needed to push to gh-pages branch
|
|
103
78
|
|
|
104
79
|
steps:
|
|
105
80
|
- name: Checkout repo
|
|
@@ -111,7 +86,7 @@ jobs:
|
|
|
111
86
|
node-version: 20
|
|
112
87
|
|
|
113
88
|
- name: Build docs
|
|
114
|
-
run:
|
|
89
|
+
run: npx explicode build
|
|
115
90
|
|
|
116
91
|
- name: Deploy to GitHub Pages
|
|
117
92
|
uses: peaceiris/actions-gh-pages@v4
|
|
@@ -120,20 +95,18 @@ jobs:
|
|
|
120
95
|
publish_dir: ./docs
|
|
121
96
|
```
|
|
122
97
|
|
|
123
|
-
This publishes to a `gh-pages` branch.
|
|
98
|
+
This workflow publishes your docs to a `gh-pages` branch. In your repository settings, enable GitHub Pages and select the root `(/)` of the `gh-pages` branch as the source.
|
|
124
99
|
|
|
125
|
-
---
|
|
126
100
|
|
|
127
101
|
## Themes
|
|
128
102
|
|
|
129
103
|
| Flag | Style |
|
|
130
104
|
|------|-------|
|
|
131
|
-
|
|
|
132
|
-
| `--dark` | GitHub Dark
|
|
105
|
+
| `none` | GitHub Light |
|
|
106
|
+
| `--dark` | GitHub Dark |
|
|
133
107
|
|
|
134
|
-
The theme is baked into `docs/ghmd.css` at build time. Re-run with or without `--dark` to switch. You can further customize `index.html` or `ghmd.css` as needed.
|
|
135
108
|
|
|
136
|
-
|
|
109
|
+
The theme is baked into `docs/ghmd.css` at build time. Re-run with or without `--dark` to switch. You can further customize `index.html` or `ghmd.css` as needed.
|
|
137
110
|
|
|
138
111
|
## Output Structure
|
|
139
112
|
|
|
@@ -149,8 +122,6 @@ docs/
|
|
|
149
122
|
<your files>.md # rendered source files
|
|
150
123
|
```
|
|
151
124
|
|
|
152
|
-
---
|
|
153
|
-
|
|
154
125
|
## License
|
|
155
126
|
|
|
156
127
|
MIT
|
package/package.json
CHANGED
|
@@ -1,7 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "explicode",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Turn your codebase into documentation.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"documentation",
|
|
7
|
+
"markdown",
|
|
8
|
+
"comments",
|
|
9
|
+
"docs",
|
|
10
|
+
"literate-programming",
|
|
11
|
+
"developer-tools",
|
|
12
|
+
"github-pages"
|
|
13
|
+
],
|
|
5
14
|
"bin": {
|
|
6
15
|
"explicode": "./cli.js"
|
|
7
16
|
},
|