herbsjs / herbsshelf Goto Github PK
View Code? Open in Web Editor NEWDynamically generated documentation for your domain
License: Other
Dynamically generated documentation for your domain
License: Other
Currently only use cases are listed and shows on Shelf's docs. It should also bring Entities as one of the primary object as well to be documented.
Does it make sense to lock the shelf route in some native way?
Optionally display it only when the environment is not production or put some password to display it?
It would be interesting to understand a entity and its relationships not only in code but also having a more "visual" approach and have this information as part of Shelf experience.
For that we could extract metadata from Herbs entity
and export to MermaidJS:
classDiagram
class User {
Number ID
String firstName
String lastName
Number age
User_Account[] accounts
}
class User_Account{
Number ID
Date expirationDate
isExpired()
}
class Project{
Number ID
String name
User_Account user
Task[] tasks
}
class Task{
Number ID
String name
Date dueDate
}
User "1" --> "*" User_Account
Project "1" --> "1" User_Account
Project "1" --> "*" Task
classDiagram
class User {
Number ID
String firstName
String lastName
Number age
User_Account[] accounts
}
class User_Account{
Number ID
Date expirationDate
isExpired()
}
class Project{
Number ID
String name
User_Account user
Task[] tasks
}
class Task{
Number ID
String name
Date dueDate
}
User "1" --> "*" User_Account
Project "1" --> "1" User_Account
Project "1" --> "*" Task
We recently used herbs to develop an offline application as a service. No layer rest or graphql;
In this case, we identified that it would be interesting to generate a folder at the root of the project with the html files.
code used generate.js
`const renderShelfHTML = require('@herbsjs/herbsshelf')
const fs = require('fs')
const yargs = require('yargs/yargs')
const { hideBin } = require('yargs/helpers')
const argv = yargs(hideBin(process.argv)).argv
const usecases = require('../../domain/usecases')
const output = argv.output ? argv.output : 'shelf'
if (!fs.existsSync(output)) {
fs.mkdirSync(output)
}
var stream = fs.createWriteStream(./${output}/index.html
)
stream.once('open', function () {
const shelf = renderShelfHTML(usecases())
stream.write(shelf)
stream.end()
})`
package.json
node generate.json --output=shelf
would it be interesting to put in the library the option to generate the html file?
Just a generic question, about whether this repository should also be an herb, since the intention is to evolve it into something bigger (playground for example)
Is your feature request related to a problem? Please describe.
Today there is already a good documentation of entities, but it would be important to make some improvements.
1.- Entity link, that is, when an entity has property, a link from one to the other would be interesting.
2. - Highlight fields that have validation and explain what type of validation is happening there.
3. - A more explicit way of mapping which use cases use that entity as input or output.
Describe the bug
When I have an entity with the field declared as a string array, it is displayed in HerbsShelf as an array of undefined.
acoes: field([String]),
To Reproduce
Steps to reproduce the behavior:
Expected behavior
A field declared as a string array in any entity should be properly displayed in HerbShelf without any 'undefined' values.
Additional context
Environment where it was possible to reproduce the bug
herbarium: 1.4.0
herbs: 1.6.1
herbs2rest: 3.0.1
herbsshelf: 4.1.0
herbarium: 1.4.0
herbs: 2.0.0
herbsshelf: 5.1.0-beta.5
With the new release of Herbarium, Herbs Shelf can generate docs using it.
Instead of custom files (ex: _uclist.js
), using Herbarium will be much simpler since it is a standardized way to access Herbs objects.
ex: renderHTML("My Project", herbarium)
where herbarium
constains all Herbs objects and its metadatas.
It is also an oportunity to include on the doc other objects like Entities (#24) and Repositories.
We need to raise the issue of client-side or server-side rendering, in the Shelf, the complexity is different for each of the cases ...
For the client-side, we will need to think about how to configure the communication between the ends, since after the page has been rendered we will no longer have access to the internal variables and functions...
For the server-side, we will need to think about how to make the environment instance, so that it does not interfere with the main application.
Exists any example to use as inspiration?
Is your feature request related to a problem? Please describe.
Today the use case documentation does not show the input or output parameters.
Describe the solution you'd like
Add this into usecase doc
Describe alternatives you've considered
An alternative would be this responsibility to stay inside the buchu, when it performs usecase.doc (or a new method), but already in a serialized way.
Describe the bug
When using single quotes on readme.md file, herbsshelf crashes, as shown bellow:
To Reproduce
npm install
npm start:dev
I noticed that if you wrap someting in single quotes (like 'this'), the error occurs. But if I remove them, the error stops.
Expected behavior
Herbsshelf should work whether or not I use single quotes in the readme file.
Today is hard to find all my Shelf's to share with my team, when I need to consult a Shelf I go to Slack and use the find every time.
Could have a place to concentrate the path to all my Shelf's, it would be much easier to find my documentation.
Like a Shelf made from Shelf's.
It would be interesting to understand a use case not only in code but also having a more "visual" approach and have this information as part of Shelf experience.
For that we could extract metadata from Herbs usecase
and export to MermaidJS:
graph TD
A([Update User Account])
B(Validate given User Account information)
C(Is User expired?)
D{If User is expired}
E(Then Activate User)
F(Else Do nothing)
G(Save User Account)
A --> B
B --> C
C --> D
D --> E
D --> F
E --> G
F --> G
Generated graph (by github / mermaid):
graph TD
A([Update User Account])
B(Validate given User Account information)
C(Is User expired?)
D{If User is expired}
E(Then Activate User)
F(Else Do nothing)
G(Save User Account)
A --> B
B --> C
C --> D
D --> E
D --> F
E --> G
F --> G
Describe the bug
In some cases, a usecase does not have a request, that is, it does not receive any value, but it returns values.
When this happens, HerbsShelf appears to have no rules for dealing with these types of usecases, which causes it to display the response in a strange way, adding an ´Object of´ that it does not add when there is a request.
usecase("Buscar fechamento do dia", {
request: {},
response: {
maioresAltas: [Stock],
maioresBaixas: [Stock],
maisNegociadas: [Stock],
deltaIbov: Number,
dataAtual: String,
},
To Reproduce
Steps to reproduce the behavior:
In any herbsjs project, create a usecase that has request {}
and that has any field as response, then open the HerbsShelf.
Expected behavior
I believe that the expected behavior is that it displays the response just like any other usecase that has request.
Screenshots
Behavior in HerbsShelf 5.0.1
Behavior in HerbsShelf 5.1.0-beta.5
Additional context
Using herbarium 1.4.0, herbs 2.0.0 and gotu 1.2.0
Is your feature request related to a problem? Please describe.
Shelf executable.
Just as swagger (https://swagger.io/) has the ability to execute requests via the interface, it would be important for the shelf to be able to execute use cases and also run test scenarios if possible.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.