Port documentation from html to markdown #564
Conversation
Use https://just-the-docs.com/ template. And setup Home page. Need to use custom deployment workflow to be able to use docs/ as source, which is slightly inconvenient compared to other themes but might allow more customisation later. The benefit of deploying docs is that the main/landing page will display automatically when clicking on docs in Github. Then navigation is straightforward.
Sections' landing pages are now rendered in github (section/README.md) and on website (section/index.html). Providing the pages permalink will make links to other pages work in both Github and website. Note the / matters at the end of the permalinks it allows to maintain directory structure (in presence of parent/child sections) or not, Fix tables of content. Links to images and test files, and old html content will break, it is fixed in following commits.
This breaks all the links, therefore needs to be fixed in following commits.
Need to use relative link to be able to render in both github and website, absolute link can only work in both cases if root is deployed (instead of docs/). Convert some html to markdown for picture, downside is resizing impossible in md.
Need to use relative link to be able to render in both github and website. Other option would be to have a dedicated src/ in each section.
More than just changing the path. For github rendering we need to - not refer to html files - use relative path since absolute path changes between website and github - permalinks ensure a similar file structure A solution to these issues would be to deploy the root of sleef, this would have the benefit of not needing a workflow and a Gemfile.
Improve/Fix tables. Simplify logo (rename and get rid of old ones).
Use ``` for code and command sections. Remove <p></p> when no alignement is needed. Reformat links using markdown Following stuff is left for later - Not sure what to do about titles, github does not allow short labels, so we would need to change the links to long titles. - Cannot autogen TOC because headers need to be in html to allow for custom labels
Rename most logos.
|
Hello @shibatch! This PR is for updating the layout of the website while facilitating maintenance work. Bonus is that the website renders in Github. Since it is quite a substantial update, but also difficult to review, we wanted to give you a heads up, to see what you think. You can see it tested inside a test project https://github.com/blapie/test-page/tree/main/docs We have reviewed this internally, so we know the website works. Still need to integrate the google verification code in to the config and fix up the favicon. |
|
Hi @shibatch, In order for us to merge this PR could you please go to https://github.com/shibatch/sleef/settings/pages, and change the Build & Deployment source to Github Actions, if that's ok? That will allow the new custom workflow to deploy the page. |
|
I'd like to start on this PR after we get some perspective on the matter I mentioned in my email earlier. |
|
I missed mentioning this because I didn't expect it to be completed so quickly, but how do you think about the idea of adopting asciidoc? |
|
hm, interesting! I have to admit I am not familiar with asciidoc. Looking at side by side comparison I do think they both offer what we need, while asciidoc maybe offers slightly more customisation. My preference would still go to markdown as it seems ubiquitous, I cannot really name a project I know that uses asciidoc. Probably my main arguments against asciidoc would be that contributors/maintainers might be more familiar with asciidoc, and also that I am unsure how well it is supported by most github page themes. Visually I think my heart still goes to plain MD versus plain AD, but that is just a matter of taste. I'm also worried of some limitations we may find further down the line, which always happens with this kind of big porting tasks. I believe MD is good enough and simple enough. If more customisation is required, I think it is still acceptable to use plain html. In a way I like how MD forces us to keep the docs simple, in not allowing too much customisation. Finally, most of the porting job is done in this patch anyway. As you said moving from MD to AD, could be a subsequent task, that's relatively simple to achieve. |
|
@brapie I changed Build & Deployment source to Github Actions. Please confirm. Here are a few things I noticed after a quick look. First of all, do we need to continue to display all partners in general? NAIST is at the top of the list because I used to belong to them, but they were very unsympathetic to my contributions to SLEEF, so I think NAIST can be erased now. RISC-V related contributions are substantial, so I think you should write better about them. In the "Compiling the library with Microsoft Visual C++" section in the User guide, please remove "&" If you are going to change the left menu to "Extra", please change the headings in the main text to that as well. Please be careful to maintain consistency. I will write again if I notice anything else. |
|
Thanks for the change and the feedback!
Rm-ed logo. Is there another institution you should be affiliated with in the docs? I updated to "formerly at NAIST".
Sure, done!
Done.
Absolutely. Done. For further docs update I'll leave it to another PR, but please feel free to submit a doc update issue, and Ill make the changes. |
|
Something is wrong with Sleef_floorf. https://blapie.github.io/test-page/2-references/libm/#sleef_floorf |
|
Good spot. Fixed! |
This allow rendering the website on both Github UI and a web page using a customisable theme (just-the-docs),while simplifying maintenance.
The theme is actively maintained and offer efficient navigation, a search engine, and a modern layout that display nicely on laptop, phones and tablets.
Test page can be previewed here
In order to separate docs from the content we need to add a Gemfile (for pluggins) and GHA workflow (for deploying website). Thus it is not as simple as adding a
_config.yml, but it could be improved in the future.Syntax highlighting can be customised later.
Some light updates of the docs but content is mostly untouched.