Create build instructions
Include a way to build for offline consumption, and to contribute / test contributions. Suggestion is to create a build.md file with this info. Also to consider automating the pylode build.
From the VF Welcome:
nolash
I simply ran the npm run build and it failed. so:
i thought id report it
i would like to know whether that is the right way to build the documentation for offline consumption
I realize there are html files pre-built, but in the event i would like to contribute something it would be practical to know 2.
lynnfoster
Yeah, I don't think you can build it with npm, although I am no expert on npm. :) But thank you for thinking to report it!
The build process we use is specific to mkdocs, https://www.mkdocs.org/user-guide/writing-your-docs/. That's sort of involved, you would have to install some things locally to build and test - steps 1-8 here https://lab.allmende.io/valueflows/valueflows/-/wikis/Website-publishing-procedure. But I'm happy to test other people's contributions, since I'm all set up for that. Or I'm happy to make changes myself based on issues people file.
I think for offline consumption, the easiest would be to clone from https://codeberg.org/valueflows/pages. And then run the index.html in the top directory.
For actually working on the source, you'd have to clone here https://lab.allmende.io/valueflows/valueflows/-/tree/master.
If you cloned from the gitlab, you could run it offline from https://lab.allmende.io/valueflows/valueflows/-/tree/master/mkdocs/site, that should be the same as the codeberg pages.
Julian Stirling
npm is a package manager for javascript
mkdocs is python not javacript
you need to pip install mkdocs and run that
pip install mkdocs
mkdocs build
lynnfoster
Thanks! :)
nolash
Julian Stirling: thanks for clearing that up. and mkdocs is to be run in the mkdocs subdir. For first-time visitors, those details would be good to have in an BUILD.md or something. Also, I noticed that the site I looked at last mentioned mkdocs-material as the build engine. is that no longer the case either?
lynnfoster
nolash
Julian Stirling: thanks for clearing that up. and mkdocs is to be run in the mkdocs subdir. For first-time visitors, those details would be good to have in an BUILD.md or something. Also, I noticed that the site I looked at last mentioned mkdocs-material as the build engine. is that no longer the case either?
Good idea, will do.
mkdocs-material is the same as mkdocs afaik, at least that is what I have meant here.
nolash
not quite i think
lynnfoster https://pypi.org/project/mkdocs-material/
lynnfoster
nolash
not quite i think
lynnfoster https://pypi.org/project/mkdocs-material/
ah thanks, yes the theme
anyhow, yes it is still mkdocs-material
nolash
also, the pylode step in your website publish guide can be accomplished with cli too, using:
12pip install pylode
pylode release-doc-in-process/all_vf.TTL -c true -p ontpub -o mkdocs/site/specification/all_vf.html
Julian Stirling
If you are using a few python packages (mkdocs, your theme, etc) You can make a python requirements.txt file. Then people can pass that to pip to install everything they need. If you make a README.md with how to install and run then it will display on GitLab automatically underneath the files