-
Notifications
You must be signed in to change notification settings - Fork 96
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Revamp documentation #452
base: master
Are you sure you want to change the base?
Revamp documentation #452
Conversation
Needs more checking
Thanks This is really great. I am very thankful to be getting rid of jekyll! Feedback on it will however need to await when I have decent dev time and can do a merge and look at everything (I need to do this because otherwise I will not understand it!). |
Just looked at your demo This is great. The top-level advert and carousel has not been moved across - I guess it is a whole load of JS. Since that top-level page is not great I think losing it is not a problem - although there should arguably be a replacement.
I guess answers to both are in the fsdocs documentation... fsdocs is much cleaner to use and maintain than Jekyll! |
Hi Professor, glad you liked the changes. I will take a look at a replacement for the top-level advert and carousel when I have time. The order of pages are decided in the frontmatter. Pages can be themed either through CSS or HTML templates. |
Demo
See a demo on my branch here.
Info
Previously, the repo relied on Jekyll to build a blog that provides a general description of Issie and the project. The blog however has gotten outdated over time and is rarely used, as it is seemingly more convenient to put information as standard markdown files within the repo.
Even further in the past, the Jekyll site also had API documentation for the functions within Issie, however functionality for this was removed at some point, and the scant documentation is out of date with the whole codebase.
This PR feature seeks to solve both problems by combining both API documentation and release/blog updates through a unified statically generated site powered by fsdocs. The F# compiler already can generate XML docs from XML comments, however fsdocs can convert this XML file (albeit with some hacking) into a neat website. The API docs are automatically updated with the master branch and the blog posts are displayed more cleanly.
Another bonus is that there is support for searching the docs, and it decently allows developers to find helpers more easily.
The build script
./build_docs.sh
is called by the GitHub Workflow in /.github to push to GitHub Pages. It can also be called in the terminal build the docs locally for quick reference, hosting them on http://localhost:8901, but the project must be compilable to do so.This PR will still require modification when deploying from the master branch, and a personal access token stored as
ISSIE_DOCS_TOKEN
under repository secrets. The token must have 'repo' scope../github/workflows/ci.yml
:Screenshots