derbynet
derbynet copied to clipboard
jeffpiazza
Web-based version of docs
Curious... would you be interested in having a web-based version of the docs, rather than using PDFs? It would make it easier for others to help maintain and improve them, as well as make the docs more searchable. I've had a lot of experience with using static-site generators for docs (like Hugo and mkdocs) and could help out with this. They'd all be written in Markdown, but converted to the normal web format.
Thoughts?
Intriguing! I think I have more questions than thoughts.
Do you have a more focused comment or request about the existing documentation? Is there a hole that needs filling? Is the concern that the existing PDFs are just boring? That they're too linear?
Would you suggest a different structure or organizing scheme?
Would web-based docs help with #176?
I'll admit I haven't walked through all of the docs, so don't know if it's worth restructuring or not at this point. We could always lift and shift what we have and then adjust as needed.
The big advantage is that you can then more easily get help with the docs, as each page would be a markdown file. It's easier than coordinating around a Word doc and then having to publish a PDF. So, I don't think it'll directly solve the referenced issue, but will allow others to make PRs as folks learn about the system and want to make the docs better, allowing you to review and respond.
If you want, I can take a first stab at setting up a doc site and let you take a look, give feedback, etc.
I am just diving into this, but I am completely lost. I can get a docker image up and running, I can use the UI int he hosted version, but I want to look at making modifications and submitting PR's. I am trying to find documentation on running the site locally. I can probably hack together everything after a few hours of digging. I see that it uses PHP, and possibly sqlite. But it seems like there should be some documentation to quickly get up and running locally, even better if it uses docker images so that I don't have to install anything for hosting and databases.
I have yet to find anything that can read the documents in the docs/ folder. Everything is just a little obtuse. Or I am. Or both.
I think you're asking, approximately: how to get a working installation from a cloned repository. Fair point that that's not at all well documented!
As a stopgap response: Here's the docker command I use locally (on Mac):
docker run -d -p 80:80 -p 443:443
-v ~/Public/DerbyNet:/var/lib/derbynet
-v /etc/localtime:/etc/localtime:ro
--mount type=bind,src='(path-to-your-local-sources)',target=/var/www/html,readonly
jeffpiazza/derbynet_server
From the cloned repository, you might need to do:
ant generated
before it can work, to build a few generated files.
As the discussion seems to have migrated to #285, I'm going to close this issue.