| Name | mdspec JSON |
| Version |
0.0.1
JSON |
| download |
| home_page | |
| Summary | Declarative plain-text specifications for objects |
| upload_time | 2023-02-03 15:57:48 |
| maintainer | |
| docs_url | None |
| author | Daniel Fairhead |
| requires_python | >=3.8,<4.0 |
| license | |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mdspec
"Declarative Model Specifications, from markdown-ish plain text files"
Looking at defining models / object specification in "plain text"
for working w/ designers & clients.
This is very much a hacky work-in-progress, / working out loud playground at the moment.
# The big idea:
Gerkin is alright for describing functional requirements - but the whole
idea of "given/when/then" is very process oriented - whereas on
Django / Wagtail / CMS based sites often have many objects defined
which automatically implement a tonne of features. (ie, A Page model
with a few fields).
They're implemented declaratively, not functionally.
Could we have something similar to gerkin for models / blocks that are declarative
not functional?
And could we use a declarative style of specification, but in a plain-english type
of format to facilitate that in a way that's easy to understand & share betweeen
techies & non-techies?
## Example:
(syntax subject to change)
```markdown
# HomePage
HomePage is a Page Type.
It has these fields:
- title : required, text, maximum 100 characters
- banner image : optional
- banner text : optional
- contents (the main contents of the page...)
The contents fields is a StreamField.
It has these blocks:
- richtext
- image
- raw-html
- contact-form
## Block definitions...
richtext is a Wagtail Block.
It has these fields:
- contents
- style
image is a Wagtail Block.
It has these fields:
- image (the link to the image itself...)
- caption
- link
...
```
Which, in theory, is relatively easy to understand for non-techies,
and renders nicely as markdown. It can be rendered out, signed off,
etc.
It's structured though, so it can be parsed (by this project) into
something we can then travese / execute as part of CI / tests.
So for instance, we can find each defined page type, check that it
has all required fields.
We could also have tests that check that the admin page for each page
type actually has all of those fields as form fields in the admin.
Once you get to anywhere where logic is involved (eg, templates, output)
then switching to gerken based cases makes a lot more sense, this
spec type would just be for things which are structurely "defined" rather
than functionally implemented... (if that makes sense?)
## Thoughts:
- anything in brakets (like this) is considered a comment, and ignored?
- markdown titles are ignored too.
- how can we have nice sections for random implementaion notes?
maybe use markdown quotation `> text` blocks? Should those be
stored to use as docstrings in generation? or better not?
# to play:
```sh
python3 mdspec/parser.py examples/pages.md
```
and it should output a structured version of the contents.
(There will be tests run with `make test` too - WIP...)
# What could we do with this?
- Use it just as a structured way to define models / pages / etc.
- Get sign off from different teams (BE / FE / Design / client...)
- Run acceptance tests automatically off the structured data.
- Generate initial model python code / tests / templates / etc?
Raw data
{
"_id": null,
"home_page": "",
"name": "mdspec",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Daniel Fairhead",
"author_email": "danthedeckie@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9c/2c/7becbc4c601dbf5d4fb2b79f99283ac2cd035105205f641fec9ea9ee07a4/mdspec-0.0.1.tar.gz",
"platform": null,
"description": "# mdspec\n\"Declarative Model Specifications, from markdown-ish plain text files\"\n\nLooking at defining models / object specification in \"plain text\"\nfor working w/ designers & clients. \n\nThis is very much a hacky work-in-progress, / working out loud playground at the moment. \n\n# The big idea:\n\nGerkin is alright for describing functional requirements - but the whole\nidea of \"given/when/then\" is very process oriented - whereas on \nDjango / Wagtail / CMS based sites often have many objects defined\nwhich automatically implement a tonne of features. (ie, A Page model\nwith a few fields).\n\nThey're implemented declaratively, not functionally.\n\nCould we have something similar to gerkin for models / blocks that are declarative\nnot functional?\n\nAnd could we use a declarative style of specification, but in a plain-english type\nof format to facilitate that in a way that's easy to understand & share betweeen\ntechies & non-techies?\n\n## Example:\n(syntax subject to change)\n\n```markdown\n# HomePage\nHomePage is a Page Type.\nIt has these fields:\n - title : required, text, maximum 100 characters\n - banner image : optional\n - banner text : optional\n - contents (the main contents of the page...)\n\nThe contents fields is a StreamField.\nIt has these blocks:\n - richtext\n - image\n - raw-html\n - contact-form\n\n## Block definitions...\n\nrichtext is a Wagtail Block.\nIt has these fields:\n - contents\n - style\n\nimage is a Wagtail Block.\nIt has these fields:\n - image (the link to the image itself...)\n - caption\n - link\n\n...\n```\n\nWhich, in theory, is relatively easy to understand for non-techies,\nand renders nicely as markdown. It can be rendered out, signed off,\netc.\n\nIt's structured though, so it can be parsed (by this project) into\nsomething we can then travese / execute as part of CI / tests.\n\nSo for instance, we can find each defined page type, check that it\nhas all required fields.\n\nWe could also have tests that check that the admin page for each page\ntype actually has all of those fields as form fields in the admin.\n\nOnce you get to anywhere where logic is involved (eg, templates, output)\nthen switching to gerken based cases makes a lot more sense, this\nspec type would just be for things which are structurely \"defined\" rather\nthan functionally implemented... (if that makes sense?)\n\n## Thoughts:\n\n- anything in brakets (like this) is considered a comment, and ignored?\n- markdown titles are ignored too.\n- how can we have nice sections for random implementaion notes?\n maybe use markdown quotation `> text` blocks? Should those be\n stored to use as docstrings in generation? or better not?\n\n# to play:\n\n\n```sh\npython3 mdspec/parser.py examples/pages.md\n```\nand it should output a structured version of the contents.\n(There will be tests run with `make test` too - WIP...)\n\n# What could we do with this?\n\n- Use it just as a structured way to define models / pages / etc.\n- Get sign off from different teams (BE / FE / Design / client...)\n- Run acceptance tests automatically off the structured data.\n- Generate initial model python code / tests / templates / etc?\n",
"bugtrack_url": null,
"license": "",
"summary": "Declarative plain-text specifications for objects",
"version": "0.0.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4aa0442ea36d7d3dd55d11b3d6a27591040b20d611fcd554e008c22c7f8f2a0b",
"md5": "5afdbbbb55b3abe865ced0b5afa7c755",
"sha256": "b05a0a8cb5e3d6702e64ee601b286fe95d7a5bb5b202ec80c745ad1d01878daa"
},
"downloads": -1,
"filename": "mdspec-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5afdbbbb55b3abe865ced0b5afa7c755",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 4749,
"upload_time": "2023-02-03T15:57:47",
"upload_time_iso_8601": "2023-02-03T15:57:47.118448Z",
"url": "https://files.pythonhosted.org/packages/4a/a0/442ea36d7d3dd55d11b3d6a27591040b20d611fcd554e008c22c7f8f2a0b/mdspec-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9c2c7becbc4c601dbf5d4fb2b79f99283ac2cd035105205f641fec9ea9ee07a4",
"md5": "a912c55a4001c5e861e76314edaac580",
"sha256": "b2f4cf148f20dd319225af7fc2ea14843fef8067b9333175102c96b482e61dfa"
},
"downloads": -1,
"filename": "mdspec-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "a912c55a4001c5e861e76314edaac580",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 4810,
"upload_time": "2023-02-03T15:57:48",
"upload_time_iso_8601": "2023-02-03T15:57:48.392969Z",
"url": "https://files.pythonhosted.org/packages/9c/2c/7becbc4c601dbf5d4fb2b79f99283ac2cd035105205f641fec9ea9ee07a4/mdspec-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-03 15:57:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "mdspec"
}
