Skip to content

Commit 026feea

Browse files
dayhaysoosdayhaysoos
committed
put back docs I accidentally deleted
1 parent 7f37aee commit 026feea

File tree

10 files changed

+2955
-3419
lines changed

10 files changed

+2955
-3419
lines changed

‎docs/docs/api.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
sidebar_position: 5
3+
---
4+
5+
# API Reference
6+
7+
The `snippetManager` is a utility for fetching and displaying code snippets in your frontend application. It handles caching, language-specific formatting, and imports.
8+
9+
## Import
10+
11+
```typescript
12+
import { snippetManager } from 'shnippet';
13+
import type { SnippetName } from '../snippets/gen-types';
14+
```
15+
16+
## Methods
17+
18+
### getSnippet
19+
20+
Fetches a snippet by name.
21+
22+
```typescript
23+
const result = await snippetManager.getSnippet('add' as SnippetName);
24+
```
25+
26+
Returns a `SnippetResult` object:
27+
```typescript
28+
interface SnippetResult {
29+
name: string;
30+
languages: string[];
31+
defaultLanguage: string;
32+
imports?: Record<string, string[]>;
33+
content: Record<string, string>;
34+
}
35+
```
36+
37+
### formatSnippet
38+
39+
Formats a snippet with optional line numbers.
40+
41+
```typescript
42+
const formatted = snippetManager.formatSnippet(snippet, {
43+
language: 'typescript',
44+
showLineNumbers: true
45+
});
46+
```
47+
48+
### updateConfig
49+
50+
> **Note**: You likely won't need to use this method. It's only necessary for advanced use cases like custom snippet servers or language-specific configurations.
51+
52+
Updates the snippet manager configuration.
53+
54+
```typescript
55+
snippetManager.updateConfig({
56+
baseUrl: 'http://your-snippet-server.com/snippets',
57+
supportedLanguages: ['typescript', 'python'],
58+
defaultImports: {
59+
typescript: ['import { useState } from "react"'],
60+
python: ['from typing import Any']
61+
}
62+
});
63+
```
64+
65+
## Example Usage
66+
67+
```typescript
68+
import { snippetManager } from 'shnippet';
69+
import type { SnippetName } from '../snippets/gen-types';
70+
71+
async function displaySnippet() {
72+
// Get the snippet
73+
const result = await snippetManager.getSnippet('add' as SnippetName);
74+
75+
// Get available languages and default language
76+
const { languages, defaultLanguage, imports, content } = result;
77+
78+
// Format with line numbers
79+
const formatted = snippetManager.formatSnippet(result, {
80+
language: defaultLanguage,
81+
showLineNumbers: true
82+
});
83+
84+
return formatted;
85+
}
86+
```
87+
88+
## Type Safety
89+
90+
The `snippetManager` works with the generated `SnippetName` type to ensure type safety:
91+
92+
```typescript
93+
import type { SnippetName } from '../snippets/gen-types';
94+
95+
// Type-safe snippet fetching
96+
const result = await snippetManager.getSnippet('add' as SnippetName); // ✅ Valid
97+
const invalid = await snippetManager.getSnippet('not-a-snippet' as SnippetName); // ❌ Type error
98+
```
99+
100+
## Configuration Options
101+
102+
| Option | Type | Description |
103+
|--------|------|-------------|
104+
| `baseUrl` | `string` | Base URL for fetching snippets |
105+
| `supportedLanguages` | `string[]` | Languages to support |
106+
| `defaultImports` | `Record<string, string[]>` | Default imports for each language |

‎docs/docs/cli.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
5+
# CLI Reference
6+
7+
Shnippet's command-line interface is the primary way to extract and manage your code snippets.
8+
9+
## Basic Usage
10+
11+
```bash
12+
# Run with default config
13+
npm run shnippet
14+
15+
# Run with custom config
16+
npm run shnippet --config ./custom.config.js
17+
18+
# Clear generated snippets
19+
npm run shnippet clear
20+
```
21+
22+
## Command Options
23+
24+
| Option | Description | Default |
25+
|--------|-------------|---------|
26+
| `--config` | Path to config file | `./shnippet.config.js` |
27+
| `--structure` | Output structure (`byLanguage` or `flat`) | `byLanguage` |
28+
| `clear` | Remove all generated snippets | - |
29+
30+
## Configuration File
31+
32+
Create a `shnippet.config.js` in your project root:
33+
34+
```javascript
35+
module.exports = {
36+
// Root directory containing your source files
37+
rootDirectory: './src',
38+
39+
// Directory where snippets will be generated
40+
snippetOutputDirectory: './snippets',
41+
42+
// File extensions to process
43+
fileExtensions: ['.js', '.ts', '.kt', '.gradle', '.xml', '.bash', '.swift', '.py'],
44+
45+
// Patterns to exclude from processing
46+
exclude: [],
47+
48+
// Custom tags for marking snippets
49+
snippetTags: {
50+
start: ':snippet-start:',
51+
end: ':snippet-end:',
52+
prependStart: ':prepend-start:',
53+
prependEnd: ':prepend-end:',
54+
},
55+
56+
// How to organize output files
57+
outputDirectoryStructure: 'byLanguage',
58+
};
59+
```
60+
61+
## Output Structure
62+
63+
> **Note**: For now, it's recommended to stick with the default `byLanguage` structure. Other options are available but may have limited support.
64+
65+
### By Language (`byLanguage`)
66+
```
67+
snippets/
68+
gen-types/
69+
index.d.ts
70+
typescript/
71+
add.snippet.txt
72+
multiply.snippet.txt
73+
python/
74+
add.snippet.txt
75+
```
76+
77+
### Flat Structure (`flat`)
78+
```
79+
snippets/
80+
gen-types/
81+
index.d.ts
82+
add.snippet.txt
83+
multiply.snippet.txt
84+
```
85+
86+
## Type Generation
87+
88+
The CLI automatically generates TypeScript types for your snippet names in `snippets/gen-types/index.d.ts`:
89+
90+
```typescript
91+
export type SnippetName = 'add' | 'multiply' | 'other-snippet';
92+
```
93+
94+
These types are updated each time you run the CLI, ensuring they stay in sync with your actual snippets.
95+
96+
## Common Tasks
97+
98+
### Extract Snippets
99+
```bash
100+
npm run shnippet
101+
```
102+
103+
### Clear Generated Files
104+
```bash
105+
npm run shnippet clear
106+
```
107+
108+
### Use Custom Config
109+
```bash
110+
npm run shnippet --config ./custom.config.js
111+
```
112+
113+
### Change Output Structure
114+
```bash
115+
npm run shnippet --structure flat
116+
```
117+
118+
## Troubleshooting
119+
120+
### No Snippets Generated
121+
- Check that your test files match the `include` patterns
122+
- Verify that your tests contain Shnippet tags
123+
- Ensure your test files are in the correct directory
124+
125+
### Configuration Errors
126+
- Make sure `shnippet.config.js` is in your project root
127+
- Verify all paths in the config are correct
128+
- Check that the config file exports a valid object
129+
130+
### Type Generation Issues
131+
- Ensure TypeScript is installed in your project
132+
- Check that your snippet names are valid identifiers
133+
- Verify the `gen-types` directory is created in your output directory

‎docs/docs/installation.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Installation
6+
7+
Get started with Shnippet in just a few steps.
8+
9+
## Prerequisites
10+
11+
- Node.js 18.0 or higher
12+
- npm 7.0 or higher
13+
- A project with tests (Jest, Vitest, or other test frameworks supported)
14+
- TypeScript (for type generation support)
15+
16+
## Installation
17+
18+
Install Shnippet as a development dependency in your project:
19+
20+
```bash
21+
npm install --save-dev shnippet
22+
```
23+
24+
## Basic Setup
25+
26+
1. Create a `shnippet.config.js` file in your project root:
27+
28+
```javascript
29+
module.exports = {
30+
// Root directory containing your source files
31+
rootDirectory: './src',
32+
33+
// Directory where snippets will be generated
34+
snippetOutputDirectory: './snippets',
35+
36+
// File extensions to process
37+
fileExtensions: ['.js', '.ts', '.kt', '.gradle', '.xml', '.bash', '.swift', '.py'],
38+
39+
// Patterns to exclude from processing
40+
exclude: [],
41+
42+
// Custom tags for marking snippets
43+
snippetTags: {
44+
start: ':snippet-start:',
45+
end: ':snippet-end:',
46+
prependStart: ':prepend-start:',
47+
prependEnd: ':prepend-end:',
48+
},
49+
50+
// How to organize output files ('byLanguage' or 'flat')
51+
outputDirectoryStructure: 'byLanguage',
52+
};
53+
```
54+
55+
Each option explained:
56+
57+
- `rootDirectory`: The main directory containing your source files
58+
- `snippetOutputDirectory`: Where generated snippets will be saved
59+
- `fileExtensions`: List of file types to process for snippets
60+
- `exclude`: Array of glob patterns to ignore
61+
- `snippetTags`: Custom markers for identifying snippets in your code
62+
- `outputDirectoryStructure`:
63+
- `byLanguage`: Organizes snippets by programming language
64+
- `flat`: Places all snippets in a single directory
65+
66+
2. Add a script to your `package.json`:
67+
68+
```json
69+
{
70+
"scripts": {
71+
"shnippet": "shnippet --config shnippet.config.js"
72+
}
73+
}
74+
```
75+
76+
## Type Generation
77+
78+
Shnippet automatically generates TypeScript types for your snippet names. After running the extractor, you'll find a `gen-types` directory in your snippets folder containing type definitions.
79+
80+
Import the types in your TypeScript files:
81+
82+
```typescript
83+
import type { SnippetName } from '../snippets/gen-types';
84+
85+
// Now you get type safety and autocomplete for snippet names
86+
const snippetName: SnippetName = 'add'; // ✅ Type-safe
87+
const invalidName: SnippetName = 'not-a-snippet'; // ❌ Type error
88+
```
89+
90+
## Verify Installation
91+
92+
Run Shnippet to verify your installation:
93+
94+
```bash
95+
npm run shnippet
96+
```
97+
98+
If everything is set up correctly, you should see:
99+
- A new `snippets` directory created with:
100+
- `gen-types/index.d.ts` containing your snippet name types
101+
- Generated snippet files organized by language
102+
- No error messages in the console
103+
104+
## Next Steps
105+
106+
- [Quick Start](./quick-start) - Learn how to write your first Shnippet
107+
- [Configuration](./configuration) - Explore all configuration options
108+
- [Examples](./examples) - See Shnippet in action with real-world examples
109+
110+
## Troubleshooting
111+
112+
### Common Issues
113+
114+
1. **No snippets generated**
115+
- Check that your test files match the `include` patterns
116+
- Verify that your tests contain Shnippet tags
117+
- Ensure your test files are in the correct directory
118+
119+
2. **Configuration errors**
120+
- Make sure `shnippet.config.js` is in your project root
121+
- Verify all paths in the config are correct
122+
- Check that the config file exports a valid object
123+
124+
3. **Type generation issues**
125+
- Ensure TypeScript is installed in your project
126+
- Check that your snippet names are valid identifiers
127+
- Verify the `gen-types` directory is created in your output directory
128+
129+
### Getting Help
130+
131+
If you encounter any issues:
132+
- Check the [GitHub Issues](https://github.com/dayhaysoos/shnippet/issues)
133+
- Open a new issue if your problem isn't already reported

0 commit comments

Comments
 (0)