From f1490d8d9297af683950ee12db699ddf999e5a26 Mon Sep 17 00:00:00 2001 From: Frank Duncan Date: Fri, 7 Jan 2022 07:55:43 -0600 Subject: [PATCH] Update project for move from github to consxy --- README.md | 10 +++--- bin/buildRelease.sh | 2 +- bin/generatedocs.sh | 2 +- docs/Changelog.md | 16 ++++++++++ docs/Reference.md | 77 +++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 100 insertions(+), 7 deletions(-) create mode 100644 docs/Changelog.md create mode 100644 docs/Reference.md diff --git a/README.md b/README.md index d8de45c..7a585a2 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,11 @@ Enforcement of documentation guidelines for my Common Lisp Projects, as well as I wish I had aspirations for this being some standard that someone else might follow, but realistically I'm just irritated at my own laziness with regard to documentation, so I wrote a solution. The forceful nature of the validator is really just because I didn't want to write a smarter parser. As an added bonus, all the docs now look the same when I look at them in the repl, so that's kind of nice. -If you like, you can [download it](https://github.com/frankduncan/sheep/releases/download/0.3/sheep_0.3.tar.gz) +If you like, you can [download it](https://consxy.com/sheep/releases/0.3/docgen_0.3.tar.gz) ## Usage -See the [wiki](https://github.com/frankduncan/sheep/wiki) for usage information (generated by this package). +See [Reference](https://consxy.com/sheep/reference.html) for usage information (generated by this package). To see how that page was created, take a look at bin/generatedocs.sh @@ -43,7 +43,7 @@ DESCRIPTION: EXAMPLES: (let ((*variable* t)) (go)) => let-it-go -```` +``` There are three required sections and one optional section. ```VALUE TYPE```, ```INITIAL VALUE```, and ```DESCRIPTION``` are freeform, with the ```EXAMPLES``` section following the same rules as below in the function documentation. @@ -53,7 +53,7 @@ There are three required sections and one optional section. ```VALUE TYPE```, ` Functions should follow the template: -```` +``` FUNC PATH => RESULT RESULT: SUCCESS-RESULTS | FAILURE-RESULT @@ -76,7 +76,7 @@ EXAMPLES: (func #P\"path/to/file.lisp\" t) => (:success \"path/to/file.lisp\") (func #P\"path/to/error.lisp\" nil) => (:failure \"path/to/error.lisp\" \"Error msg\") -```` +``` There are four sections to each function definition: diff --git a/bin/buildRelease.sh b/bin/buildRelease.sh index 1146c38..4df8aca 100755 --- a/bin/buildRelease.sh +++ b/bin/buildRelease.sh @@ -10,4 +10,4 @@ cp -ap src/main/* sheep_$version/ tar zcf sheep_${version}.tar.gz sheep_$version/ rm -rf sheep_$version -echo "All done, it's in sheep_${version}.tar.gz, you should tag it and push it up to github" +echo "All done, it's in sheep_${version}.tar.gz, you should tag it, push it up to consxy, and update the consxy releases" diff --git a/bin/generatedocs.sh b/bin/generatedocs.sh index ba42754..953f4ba 100755 --- a/bin/generatedocs.sh +++ b/bin/generatedocs.sh @@ -4,4 +4,4 @@ sbcl \ --eval "(asdf:load-system :sheep)" \ --eval "(format t \"----~%\")" \ --eval "(format t \"~A\" (sheep:export-package :sheep))" \ - --eval "(quit)" 2> /dev/null | sed -n '/^----$/,$p' | tail -n +2 > wiki/Home.md + --eval "(quit)" 2> /dev/null | sed -n '/^----$/,$p' | tail -n +2 > docs/Reference.md diff --git a/docs/Changelog.md b/docs/Changelog.md new file mode 100644 index 0000000..f0c3add --- /dev/null +++ b/docs/Changelog.md @@ -0,0 +1,16 @@ +# Changelog +## [0.3](https://code.consxy.com/gitweb/gitweb.cgi/sheep/commit/0.3) +* Remove need for ARGUMENTS AND VALUES when there are none [d898031](http://code.consxy.com/gitweb/gitweb.cgi/sheep/d898031) +## [0.2](https://code.consxy.com/gitweb/gitweb.cgi/sheep/commit/0.2) +* Add variable documentation [0d2cc28](http://code.consxy.com/gitweb/gitweb.cgi/sheep/0d2cc28) +* Improve travis functionality [2d880c9](http://code.consxy.com/gitweb/gitweb.cgi/sheep/2d880c9) +* Fix bug with pretty-print-validate-packages [8647326](http://code.consxy.com/gitweb/gitweb.cgi/sheep/8647326) +* Post release update [93043f5](http://code.consxy.com/gitweb/gitweb.cgi/sheep/93043f5) +## [0.1](https://code.consxy.com/gitweb/gitweb.cgi/sheep/commit/0.1) +* Add documentation and generator. [1ba7b00](http://code.consxy.com/gitweb/gitweb.cgi/sheep/1ba7b00) +* Add structure documentation [e9d1b7d](http://code.consxy.com/gitweb/gitweb.cgi/sheep/e9d1b7d) +* Add holistic checking [2a64bd9](http://code.consxy.com/gitweb/gitweb.cgi/sheep/2a64bd9) +* Add package documentation [683928f](http://code.consxy.com/gitweb/gitweb.cgi/sheep/683928f) +* Add function documentation checker/converter [4c8ef06](http://code.consxy.com/gitweb/gitweb.cgi/sheep/4c8ef06) +* Setting up repository [a731941](http://code.consxy.com/gitweb/gitweb.cgi/sheep/a731941) +* Initial commit [b9787e5](http://code.consxy.com/gitweb/gitweb.cgi/sheep/b9787e5) diff --git a/docs/Reference.md b/docs/Reference.md new file mode 100644 index 0000000..bd4e623 --- /dev/null +++ b/docs/Reference.md @@ -0,0 +1,77 @@ +# Package SHEEP + +Main sheep package. + +Use sheep to validate that documentation strings on external symbols adhere to a strict format and exist, so that they can be output to markdown format, while looking decent when used within a common lisp process. + +## Contents + +* **function [export-package](#function-export-package)** - _export-package_ takes in _pkg_ and converts all the documentation for the symbols into markdown with the hope of emulating the hyperspec style. +* **function [pretty-print-validate-packages](#function-pretty-print-validate-packages)** - _pretty-print-validate-packages_ takes _pkgs_ and runs validation on all of them. It dumps to standard out failures as it comes upon them, finally returning whether it was successful or not. +* **function [validate-package](#function-validate-package)** - _validate-package_ takes in _pkg_ and validates that all the external symbols adhere to documentation guidelines, exist, and can be parsed to be used for exporting. +* **condition [validation-failure](#condition-validation-failure)** - Used internally for sheep parts to signal a validation error. + +## Function **EXPORT-PACKAGE** + +#### Syntax: + +**export-package** _pkg_ => _markdown_ + +#### Arguments and Values: + +_pkg_---A package symbol +_markdown_---A string containing the markdown representation of this packages documentation + +#### Description: + +_export-package_ takes in _pkg_ and converts all the documentation for the symbols into markdown with the hope of emulating the hyperspec style. + +It should only be run after the package has been validated, as it assumes that all documentation it gets will be valid. + +## Function **PRETTY-PRINT-VALIDATE-PACKAGES** + +#### Syntax: + +**pretty-print-validate-packages** _&rest_ _pkgs_ => _success_ + +```pkgs::= pkg*``` + +#### Arguments and Values: + +_success_---Whether or not all symbols passed validation +_pkg_---A package symbol + +#### Description: + +_pretty-print-validate-packages_ takes _pkgs_ and runs validation on all of them. It dumps to standard out failures as it comes upon them, finally returning whether it was successful or not. + +This can be used in validation tests to ensure that documentation can be generated at a later date. + +#### Examples: + +```(pretty-print-validate-packages :pkg1 :pkg2)``` => ```t``` + +## Function **VALIDATE-PACKAGE** + +#### Syntax: + +**validate-package** _pkg_ => _failures_ + +```failures::= failure*``` +```failure::= (:failure symb msg)``` + +#### Arguments and Values: + +_pkg_---A package symbol +_symb_---Symbol the check failed on +_msg_---Message containing information about the failure + +#### Description: + +_validate-package_ takes in _pkg_ and validates that all the external symbols adhere to documentation guidelines, exist, and can be parsed to be used for exporting. + +Only one error per symbol will be reported at a time, all concatenated to a list in the aforementioned form. + +## Condition VALIDATION-FAILURE + +Used internally for sheep parts to signal a validation error. -- 2.25.1