Open SimonBiggs opened 6 years ago
SimonBiggs
commented
6 years ago @OxygenLithium @robmarkcole @sunyu0410 what's your opinion about having feature and bug fixes go on hold for a few weeks while I sort out the docs?
Once we're happy with 0.9.1dev3 I'll release it as 0.9.1 proper. And then focus on docs. This means issues such as colunn hiding, and that bug with the table options will go on hold for a bit.
robmarkcole
commented
6 years ago Hi @SimonBiggs I agree that documentation should be the priority at this point, but still with essential bugfixes addressed.
Your approach sounds very novel so I am looking forward to seeing it in action! Will you be using https://jekyllrb.com/ ? Home-assistant use it and I really appreciate the simplicity of just editing markdown to create the website. This actually gave me another thought; that if scriptedforms can be used to embed live examples of python into webpages that could potentially be a huge draw to the code as a use for documentation? Cheers
SimonBiggs
commented
6 years ago Yeah, where essential bugfix == show stoppers, so not any on the list at the moment.
I have used quite a bit of Jekyll and I do really like it. I don't think it fits here as the main benefit you mentioned is the use of markdown files, we already have that built in with ScriptedForms itself.
Every so often I have considered using the 'yaml header' idea from Jekyll within ScriptedForms:
https://jekyllrb.com/docs/frontmatter/
But for the aim of simplicity I have avoided as I have always thought of another way to achieve the same thing.
For local webpages where you trust the users of the site, sure. For public webpages something like binder would need to be used to sandbox and deploy the website. One day I was thinking of setting up a 'do it yourself binder website deploy', but that's a long way away.
robmarkcole
commented
6 years ago Lets avoid any yaml :)
SimonBiggs
commented
6 years ago Sounds like a plan :)
So the more I think about it, as great as fixing the current priority issues/enhancements I think this needs to be bumped to the top.
The idea is that when the "book" looking icon is clicked, the live documentation running on that jupyter server will boot up. I want to be able to have the documentation be the foundation for the testing suite. Each example presented in the docs will be interacted with via selenium to create the tests. The examples in the docs will be located right next to the files that correspond to them. The text explaining that feature will actually be written within the code files themselves. The docs will extract that text out and present it within the documentation.
The docs will be split into user docs and development docs. The aim is that each file in the source code will have a document somewhere in the documentation explaining what that file is for. An explanation which is itself extracted from that file which is being explained. The top level user facing features will have their explanation within the user docs. Any other file will fall into the contributor docs.
Ideally I'll use python to do a glob of the source code directory. Then search for documentation within the source files. The table of contents for the development docs can mimic the file tree of the source. The user docs will need something else...