docs: add docsite to repository (closes #2)

Author: d-sys-admin

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: docs 
+on:
+  push:
+    branches:
+      - master 
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache 
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs mkdocs-terminal mkdocs-git-revision-date-plugin 'mkdocs-spellcheck[symspellpy]' mkdocs-llmstxt mkdocs-rss-plugin mkdocs-ultralytics-plugin
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -1,3 +1,7 @@
 node_modules
 coverage
-.env
+.env
+.DS_Store
+.site
+site
+.cache

README.md

@@ -19,6 +19,7 @@
 - [setting up x api credentials](#setting-up-x-api-credentials)
 - [development](#development)
 - [contributing](#contributing)
+- [documentation](#documentation)
 - [support this project](#-support-this-project)
 - [license](#license)
 
@@ -201,6 +202,21 @@ contributions are welcome! here's how you can help:
 
 please make sure your code passes all tests and follows the project's coding style.
 
+## 📚 documentation
+
+comprehensive documentation for this project is available on our dedicated documentation site at [https://captradeoff.github.io/x-post-action/](https://captradeoff.github.io/x-post-action/). the site is built using the [d-sys-wiki documentation template](https://github.com/captradeoff/d-sys-wiki-documentation-template).
+
+the documentation includes:
+- detailed usage instructions
+- api reference
+- configuration options
+- examples and tutorials
+- troubleshooting guides
+
+the documentation source files are located in the `docs/` directory of this repository. you can contribute to the documentation by submitting pull requests to update these files.
+
+visit the documentation site to learn more about how to effectively use this action in your workflows.
+
 ## ⭐ support this project
 
 if you find this project useful, please consider:

docs/credentials.md

@@ -0,0 +1,57 @@
+# 🔑 setting up x api credentials
+
+to use the x post action, you'll need to set up a developer account and create an app on x.
+
+## step 1: create a developer account
+
+1. go to the [x developer portal](https://developer.twitter.com/en/portal/dashboard)
+2. sign in with your x account
+3. apply for a developer account if you don't already have one
+
+## step 2: create a new app
+
+1. in the developer portal, navigate to "projects & apps" 
+2. click "create app"
+3. fill in the required information about your app
+4. set the app permissions to "read and write"
+
+## step 3: generate access tokens
+
+1. from your app's dashboard, navigate to the "keys and tokens" tab
+2. generate consumer keys (app key and app secret)
+3. generate access token and access token secret
+
+## step 4: add credentials to github secrets
+
+1. in your github repository, go to settings > secrets and variables > actions
+2. click "new repository secret"
+3. add the following secrets:
+   - `X_APP_KEY`: your app key
+   - `X_APP_SECRET`: your app secret
+   - `X_ACCESS_TOKEN`: your access token
+   - `X_ACCESS_SECRET`: your access token secret
+
+## step 5: use secrets in your workflow
+
+reference the secrets in your workflow file:
+
+```yaml
+- name: post to x
+  uses: captradeoff/x-post-action@v1
+  with:
+    appKey: ${{ secrets.X_APP_KEY }}
+    appSecret: ${{ secrets.X_APP_SECRET }}
+    accessToken: ${{ secrets.X_ACCESS_TOKEN }}
+    accessSecret: ${{ secrets.X_ACCESS_SECRET }}
+    message: 'hello from github actions!'
+```
+
+## troubleshooting credentials
+
+if you encounter authentication issues:
+
+1. verify that all four credentials are correctly stored in github secrets
+2. ensure your app has "read and write" permissions
+3. check that your access tokens haven't expired
+4. make sure your developer account is in good standing
+5. verify that you haven't exceeded rate limits 

docs/description.md

@@ -0,0 +1,17 @@
+# 📝 description
+
+this action allows you to automatically post messages to x from your github workflow.
+
+it can be used to announce new releases, share updates, or integrate your github workflow with x communities.
+
+## what it does
+
+the x post action simplifies the process of posting to x (formerly twitter) directly from your github workflows. using the twitter api v2, this action enables automated social media updates whenever significant events occur in your repository.
+
+## use cases
+
+- announce new software releases with version information
+- share project updates, milestones and achievements
+- notify your audience about bug fixes and important patches
+- build an engaged community around your open source project
+- integrate your development pipeline with social media outreach 

docs/development/contributing.md

@@ -0,0 +1,58 @@
+# 🤝 contributing
+
+contributions are welcome! this page explains how you can help improve the x post action.
+
+## ways to contribute
+
+there are many ways to contribute to this project:
+
+- report bugs and suggest features through issues
+- fix bugs and implement new features
+- improve documentation
+- write tests
+- share the project with others
+
+## contribution workflow
+
+1. **fork the repository**: click the fork button at the top of the [repository page](https://github.com/captradeoff/x-post-action)
+2. **create a feature branch**: `git checkout -b feature/your-feature-name`
+3. **make your changes**: implement your feature or fix
+4. **write or update tests**: ensure your code is well-tested
+5. **ensure tests pass**: run `npm test` to make sure everything works
+6. **build the action**: run `npm run build` to update the dist folder
+7. **commit your changes**: `git commit -m 'add some feature'`
+8. **push to the branch**: `git push origin feature/your-feature-name`
+9. **open a pull request**: go to your fork on github and click the 'new pull request' button
+
+## pull request guidelines
+
+when submitting a pull request:
+
+- fill in the required template
+- add a clear title and description
+- reference any relevant issues
+- include screenshots and animated gifs if appropriate
+- ensure all tests are passing
+- make sure you've built the action with `npm run build`
+
+## code style
+
+please make sure your code follows the project's coding style:
+
+- use camelCase for variable and function names
+- include jsdoc comments for functions
+- keep functions small and focused
+- use meaningful variable names
+- add appropriate error handling
+
+## ⭐ supporting the project
+
+if you find this project useful, please consider:
+
+- ⭐ starring the repository on github
+- 🔄 forking the repository to contribute
+- 📢 sharing the project with others who might find it helpful
+- 🐛 reporting bugs or suggesting features through issues
+- 💻 submitting pull requests to improve the code or documentation
+
+your support helps maintain and improve this project! 

docs/development/getting-started.md

@@ -0,0 +1,66 @@
+# 💻 development
+
+this project uses node.js and the twitter api v2 client.
+
+## prerequisites
+
+before you begin, ensure you have:
+
+- node.js (v20 recommended)
+- npm
+- git
+- x developer account and api credentials
+
+## setting up local development
+
+1. clone the repository:
+   ```bash
+   git clone https://github.com/captradeoff/x-post-action.git
+   cd x-post-action
+   ```
+
+2. install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. for testing with actual api calls, create a `.env` file:
+   ```bash
+   cp .env.sample .env
+   ```
+   
+4. edit the `.env` file to add your x api credentials
+
+## project structure
+
+- `index.js`: main entry point
+- `action.yaml`: github action definition
+- `index.test.js`: unit tests
+- `integration.test.js`: api integration tests
+- `integration-action.test.js`: action function tests
+- `dist/`: compiled action code
+
+## building the action
+
+the action uses @vercel/ncc to compile the node.js code and dependencies into a single file:
+
+```bash
+npm run build
+```
+
+this will create a `dist/index.js` file that is referenced in `action.yaml`.
+
+## development workflow
+
+1. make changes to the code
+2. update or add tests to cover your changes
+3. run tests to ensure everything works:
+   ```bash
+   npm test
+   ```
+4. build the action:
+   ```bash
+   npm run build
+   ```
+5. commit and push your changes
+6. create a pull request 

docs/development/testing.md

@@ -0,0 +1,66 @@
+# testing
+
+this project uses jest for testing with both unit tests and integration tests.
+
+## unit tests
+
+the unit tests mock the twitter api and github actions core module to verify functionality without making actual api calls.
+
+to run the unit tests:
+
+```bash
+npm test
+```
+
+this will run all test files matching `*.test.js` in the project root.
+
+coverage report is generated automatically when running the tests. you can view the html coverage report in the `coverage` directory.
+
+## integration tests
+
+integration tests make actual calls to the x api to verify real-world functionality.
+
+### setup for integration tests
+
+1. copy the `.env.sample` file to `.env` and fill in with your x api credentials:
+   ```bash
+   cp .env.sample .env
+   ```
+
+2. edit the `.env` file and replace placeholders with your actual api keys and tokens:
+   ```
+   X_APP_KEY=your_actual_app_key
+   X_APP_SECRET=your_actual_app_secret
+   X_ACCESS_TOKEN=your_actual_access_token
+   X_ACCESS_SECRET=your_actual_access_secret
+   ```
+
+### running integration tests
+
+there are several integration test scripts available:
+
+```bash
+# run direct api integration test
+npm run test:integration
+
+# run action function integration test
+npm run test:integration-action
+
+# run all integration tests
+npm run test:integration-all
+```
+
+### integration test details
+
+the integration tests include:
+
+- **direct api test**: tests the x api directly using credentials from .env
+- **action function test**: tests the postTweet function exported from index.js
+
+both tests will:
+- post actual tweets to your x account
+- include extensive logging for debugging
+- skip tests automatically if environment variables aren't set
+- add a timestamp to make each test message unique
+
+**note:** be careful with integration tests as they make real api calls and will post actual tweets to your account.