Merge pull request #1014 from Dynamoid/ak/move-out-guides-from-readme

Move out documentation from README.md

Author: andrykonchin

.github/workflows/mdbook.yml

@@ -0,0 +1,61 @@
+name: Deploy Documentation
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-guides:
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.5.2
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mdBook
+        run: |
+          wget https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz
+          tar xzf mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with mdBook
+        run: ./mdbook build
+
+      - name: Move into a dedicated subdirectory
+        run: |
+          mkdir -p combined-docs/guides
+          cp -r build/ combined-docs/guides
+
+      - name: Upload static files as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: combined-docs
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build-guides
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -10,6 +10,9 @@ rdoc
 .yardoc
 /_yardoc/
 
+# mdbook generated
+book
+
 # bundler
 /.bundle/
 
@@ -60,7 +63,6 @@ rdoc
 .tags
 .tags_sorted_by_file
 
-/doc/
 /spec/reports/
 /tmp/
 /spec/DynamoDBLocal-latest/

.rubocop.yml

@@ -65,9 +65,6 @@ Style/TrailingCommaInArguments:
   Enabled: false
 Style/UnlessElse:
   Enabled: false
-Style/OneClassPerFile:
-  Exclude:
-    - 'README.md'
 
 # We aren't so brave to tackle all these issues right now
 Layout/LineLength:
@@ -111,10 +108,20 @@ Naming/PredicateMethod:
 Security/YAMLLoad:
   Enabled: false
 
+# disable some copes in documenting Markdown files
 Lint/EmptyClass:
   Exclude:
     - README.md
+    - 'doc/**/*'
 Lint/EmptyBlock:
   Exclude:
     - README.md
-
+    - 'doc/**/*'
+Layout/ExtraSpacing:
+  Exclude:
+    - 'README.md'
+    - 'doc/**/*'
+Style/OneClassPerFile:
+  Exclude:
+    - 'README.md'
+    - 'doc/**/*'

CONTRIBUTING.md

@@ -15,7 +15,7 @@ installed and launched when you need either to run specs or to work in
 a REPL. See the [dynamodb-local](#dynamodb-local) section below for more details.
 
 
-## Specs
+## Running Specs
 
 The specs are written with RSpec and are supposed to be run against
 _dynamodb-local_ only.
@@ -114,7 +114,10 @@ $ bin/console
 # dynamodb-local
 
 _dynamodb-local_ is software provided by Amazon to emulate DynamoDB and
-run it locally. See [official documentation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) to install it.
+run it locally. There are several ways to install it locally (see the [official documentation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html)).
+
+
+## Run dynamodb-local with Docker
 
 To run _dynamodb-local_ using a Docker image use the following command
 (installs the Docker image automatically):
@@ -125,12 +128,43 @@ $ docker run --rm -d -p 8000:8000 amazon/dynamodb-local
 
 A Docker Compose file is also provided.
 
+
+## Run dynamodb-local manually
+
 To run _dynamodb-local_ as a JAR (that should be already downloaded)
 there are the following scripts to run and stop it:
 
 - `bin/start_dynamodblocal`
 - `bin/stop_dynamodblocal`
 
+Use the following workflow:
+
+ * First download and unpack the latest version of DynamoDB. We have a
+   script that will do this for you if you use bash, and homebrew on a Mac.
+
+    ```shell
+    bin/setup
+    ```
+
+ * Start the local instance of DynamoDB to listen in ***8000*** port
+
+    ```shell
+    bin/start_dynamodblocal
+    ```
+
+ * and lastly, use `rake` to run the tests.
+
+    ```shell
+    rake
+    ```
+
+ * When you are done, remember to stop the local test instance of
+   dynamodb
+
+    ```shell
+    bin/stop_dynamodblocal
+    ```
+
 
 ## Pull Requests
 
@@ -149,3 +183,10 @@ There are the following requirements for new Pull Requests:
 > necessary to blindly follow its recommendations if it hurts readability
 > or simplicity of code.
 
+
+## Related links
+
+This documentation you may find useful:
+- <https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/welcome.html>
+- <https://docs.aws.amazon.com/sdk-for-ruby/v3/api/index.html>
+