From c3ae280899376e2288a1957fb3b85bf32123ace5 Mon Sep 17 00:00:00 2001 From: Roy Allen Sutton Date: Tue, 12 Dec 2023 10:48:26 -0600 Subject: [PATCH] Documentation update. --- .gitignore | 5 +- README.md | 2 +- docs/Gemfile | 4 + docs/Gemfile.lock | 272 ++++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 90 ++------------- docs/_config.yml | 18 ++- docs/flow.md | 16 +-- 7 files changed, 312 insertions(+), 95 deletions(-) create mode 100644 docs/Gemfile create mode 100644 docs/Gemfile.lock diff --git a/.gitignore b/.gitignore index 181a945..1c0ec53 100644 --- a/.gitignore +++ b/.gitignore @@ -32,11 +32,10 @@ Makefile.in /work/ # -# GitHub docs related +# GitHub Pages # -/docs/Gemfile -/docs/Gemfile.lock +/docs/.bundle/ /docs/_site/ /docs/_staging/ diff --git a/README.md b/README.md index 78ae33e..9b8b54a 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ openscad-amu [![GPL licensed](https://img.shields.io/badge/license-GPL-blue.svg?style=flat)](https://raw.githubusercontent.com/royasutton/openscad-amu/master/COPYING) -View live docs on [GitHib Pages](https://royasutton.github.io/openscad-amu). +View live docs on [GitHub Pages](https://royasutton.github.io/openscad-amu). Evaluation diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..7a42359 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,4 @@ +source 'https://rubygems.org' +gem 'github-pages', group: :jekyll_plugins + +gem "webrick", "~> 1.8" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 0000000..a041f7e --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,272 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (7.1.2) + base64 + bigdecimal + concurrent-ruby (~> 1.0, >= 1.0.2) + connection_pool (>= 2.2.5) + drb + i18n (>= 1.6, < 2) + minitest (>= 5.1) + mutex_m + tzinfo (~> 2.0) + addressable (2.8.6) + public_suffix (>= 2.0.2, < 6.0) + base64 (0.2.0) + bigdecimal (3.1.4) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.11.1) + colorator (1.1.0) + commonmarker (0.23.10) + concurrent-ruby (1.2.2) + connection_pool (2.4.1) + dnsruby (1.70.0) + simpleidn (~> 0.2.1) + drb (2.2.0) + ruby2_keywords + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.16.0) + ffi (>= 1.15.0) + eventmachine (1.2.7) + execjs (2.9.1) + faraday (2.7.12) + base64 + faraday-net_http (>= 2.0, < 3.1) + ruby2_keywords (>= 0.0.4) + faraday-net_http (3.0.2) + ffi (1.16.3) + forwardable-extended (2.6.0) + gemoji (3.0.1) + github-pages (228) + github-pages-health-check (= 1.17.9) + jekyll (= 3.9.3) + jekyll-avatar (= 0.7.0) + jekyll-coffeescript (= 1.1.1) + jekyll-commonmark-ghpages (= 0.4.0) + jekyll-default-layout (= 0.1.4) + jekyll-feed (= 0.15.1) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.13.0) + jekyll-include-cache (= 0.2.1) + jekyll-mentions (= 1.6.0) + jekyll-optional-front-matter (= 0.3.2) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.3.0) + jekyll-redirect-from (= 0.16.0) + jekyll-relative-links (= 0.6.1) + jekyll-remote-theme (= 0.4.3) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.8.0) + jekyll-sitemap (= 1.4.0) + jekyll-swiss (= 1.0.0) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) + jekyll-titles-from-headings (= 0.5.3) + jemoji (= 0.12.0) + kramdown (= 2.3.2) + kramdown-parser-gfm (= 1.1.0) + liquid (= 4.0.4) + mercenary (~> 0.3) + minima (= 2.5.1) + nokogiri (>= 1.13.6, < 2.0) + rouge (= 3.26.0) + terminal-table (~> 1.4) + github-pages-health-check (1.17.9) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (~> 4.0) + public_suffix (>= 3.0, < 5.0) + typhoeus (~> 1.3) + html-pipeline (2.14.3) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.8.0) + i18n (1.14.1) + concurrent-ruby (~> 1.0) + jekyll (3.9.3) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (>= 0.7, < 2) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (>= 1.17, < 3) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-avatar (0.7.0) + jekyll (>= 3.0, < 5.0) + jekyll-coffeescript (1.1.1) + coffee-script (~> 2.2) + coffee-script-source (~> 1.11.1) + jekyll-commonmark (1.4.0) + commonmarker (~> 0.22) + jekyll-commonmark-ghpages (0.4.0) + commonmarker (~> 0.23.7) + jekyll (~> 3.9.0) + jekyll-commonmark (~> 1.4.0) + rouge (>= 2.0, < 5.0) + jekyll-default-layout (0.1.4) + jekyll (~> 3.0) + jekyll-feed (0.15.1) + jekyll (>= 3.7, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.13.0) + jekyll (>= 3.4, < 5.0) + octokit (~> 4.0, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-mentions (1.6.0) + html-pipeline (~> 2.3) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-redirect-from (0.16.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.3) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) + rubyzip (>= 1.3.0, < 3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-swiss (1.0.0) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.6.0) + jekyll (> 3.5, < 5.0) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.12.0) + gemoji (~> 3.0) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + kramdown (2.3.2) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.8.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.3.6) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.20.0) + mutex_m (0.2.0) + nokogiri (1.15.5-x86_64-linux) + racc (~> 1.4) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (4.0.7) + racc (1.7.3) + rb-fsevent (0.11.2) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.6) + rouge (3.26.0) + ruby2_keywords (0.0.5) + rubyzip (2.3.2) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.9.2) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + simpleidn (0.2.1) + unf (~> 0.1.4) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + typhoeus (1.4.1) + ethon (>= 0.9.0) + tzinfo (2.0.6) + concurrent-ruby (~> 1.0) + unf (0.1.4) + unf_ext + unf_ext (0.0.9.1) + unicode-display_width (1.8.0) + webrick (1.8.1) + +PLATFORMS + x86_64-linux + +DEPENDENCIES + github-pages + webrick (~> 1.8) + +BUNDLED WITH + 2.4.22 diff --git a/docs/README.md b/docs/README.md index 0eb4fb6..3797411 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,6 @@ [![GPL licensed](https://img.shields.io/badge/license-GPL-blue.svg?style=flat)](https://raw.githubusercontent.com/royasutton/openscad-amu/master/COPYING) - What is it? ----------- @@ -28,7 +27,6 @@ for use in code testing, code documentation and design construction. Moreover, with GNU make, targets can be constructed in parallel which drastically reduces compile times for larger design projects. - The Design Flow --------------- @@ -65,91 +63,25 @@ As the design size increases, so does the benefit of using [openscad-amu]. Compiling design targets one-by-one is times consuming and error prone and discourages design optimization and/or exploration. -> *For larger design projects, the increase in benefit is significant as -> [openscad-amu] frees designers from mundane dependency and state -> tracking and provides mechanisms for part compilation and coherent -> design documentation.* - -A significant side effect is greatly reduce total project compile time -on multi-processor systems via parallel invocations of the +A windfall is a linear reduction, with processor thread count, in +compile time on multi-processor systems via parallel invocations of the single-threaded [OpenSCAD] compiler. Once compilation flows are -described, using the simple scripting scheme, each design target is -kept current from source as needed via invocations of `make`. - -> *For smaller projects, the ability to document a design or library using -> [Doxygen] is a convenient way to both maintain and publish the design -> interface or API.* - - -Getting Started ---------------- - -If you are already familiar with [Doxygen], adding basic documentation -to your [OpenSCAD] designs using [openscad-amu] is straight forward. -Simply markup each of your design files with the [special commands], -name each file in the project makefile, and type `make` to generate -your documentation. - -You can also start from a template created by the `setup-amu.bash` -script, then customize as needed as described in the [evaluation] -section of the repository home page. - -### Setup ### - -See the GitHub source [repository] for instructions on -[evaluating][evaluation] and [installing]. - - -Example -------- - -* [A Portable solar panel tripod mount](http://www.thingiverse.com/thing:2051608): - - This design took approximately 48 hours from concept to assembly and - documentation using [omdl] and [openscad-amu]. It demonstrates the - automated design flow. One can change a design parameter, then type - `make all` to recompile effected parts. In this design, parts are - engraved with a version and part identifier using a simple database - scheme available in [omdl]. - +described, using the openscad-amu scripting scheme, each design target +is kept current from source as needed during automatic build processing +via [GNU make]. -Contributing ------------- +To get started using [openscad-amu], please see the GitHub source +[repository]. -openscad-amu uses [git] for development tracking, and is hosted on -[GitHub] following the usual practice of [forking] and submitting -[pull requests] to the source [repository]. - -As it is released under the [GNU General Public License], any file you -change should bear your copyright notice alongside the original -authors' copyright notices typically located at the top of each file. - - -Contact and Support -------------------- - -In case you have any questions or would like to make feature requests, -you can contact the maintainer of the project or file an [issue]. - - -[GNU General Public License]: https://www.gnu.org/licenses/gpl.html -[GNU Make]: https://www.gnu.org/software/make [openscad-amu]: https://royasutton.github.io/openscad-amu [repository]: https://github.com/royasutton/openscad-amu -[issue]: https://github.com/royasutton/openscad-amu/issues - -[evaluation]: https://github.com/royasutton/openscad-amu#evaluation -[installing]: https://github.com/royasutton/openscad-amu#installing -[omdl]: https://royasutton.github.io/omdl - -[OpenSCAD]: http://www.openscad.org/ +[GNU Make]: https://www.gnu.org/software/make [Doxygen]: http://www.doxygen.nl [special commands]: http://www.doxygen.nl/manual/commands.html -[git]: http://git-scm.com/ -[GitHub]: http://github.com/ -[forking]: http://help.github.com/forking/ -[pull requests]: https://help.github.com/articles/about-pull-requests/ +[OpenSCAD]: http://www.openscad.org/ + +[omdl]: https://royasutton.github.io/omdl diff --git a/docs/_config.yml b/docs/_config.yml index c419263..055ae64 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1 +1,17 @@ -theme: jekyll-theme-cayman \ No newline at end of file +# +# Jekyll configuration +# +# https://help.github.com/categories/customizing-github-pages +# https://help.github.com/articles/configuring-jekyll +# https://jekyllrb.com/docs/configuration +# + +# GitHub Pages theme +theme: jekyll-theme-cayman + +# versions +vopenscad: 2021.01 + +# +# eof +# diff --git a/docs/flow.md b/docs/flow.md index 8e744b9..442c208 100644 --- a/docs/flow.md +++ b/docs/flow.md @@ -5,24 +5,18 @@ The Design Flow

-A project includes a makefile, the project source files, and a -Doxygen configuration file (Doxyfile). Source files may be -annotated with documentation and/or build automation scripts. Each -script is extracted at compile time to generate a _scope_ makefile that -controls the generation of corresponding targets. +A project includes a makefile, the project source files, and a Doxygen +configuration file (Doxyfile). Source files may be annotated with +documentation and/or build automation scripts. Each script is extracted +at compile time to generate a _scope_ makefile that controls the +generation of corresponding targets. [openscad-amu] brings together [OpenSCAD], [Doxygen], [GNU Make], and _custom scripting_ (based on [GNU Bash]) to automate the generation of the design documentation and design targets. -**Moreover**, with openscad-amu, a repository of OpenSCAD library -documentation is maintained for each library it installs, as with this -example [Library Documentation] index. - [openscad-amu]: https://royasutton.github.io/openscad-amu [OpenSCAD]: http://www.openscad.org [Doxygen]: http://www.doxygen.nl [GNU Make]: https://www.gnu.org/software/make [GNU Bash]: https://www.gnu.org/software/bash - -[Library Documentation]: https://royasutton.github.io/omdl/api/html/index.html