Comments (14)
Would changing to a modern theme (like the Material for MkDocs) being an option. It would still require additional work to review and fix issues, but the theme would provide existing Markdown features for the notes part for example.
I asking before working on the integration of a new theme.
from oi-docs.
I am tempted to say yes, as there is also Spacelab and Solar available. So we have some more thourough designed art and colorspace options that are pleasing on the eye. It depends if we want to keep the colorscheme we have now. If not I my vote goes towards a new theme. And I am not fond of our current coloscheme.
from oi-docs.
The primary problem with #220 was the formatting elements for the "notes" and "warning" section were not supported and these sections weren't displayed at all. There were some other parts of the site which has similar problems.
This isn't to say that MkDocs can't or shouldn't be upgraded. If there's a different theme which supports the formatting element we use then that seems like a good solution.
from oi-docs.
I would rewrite the notes part to match the required style for the mkdocs markdown extension used by the theme.
I will work on that during the weekend and prepare a testing branch for you all.
from oi-docs.
Maybe the expression"update mkdocs" is a little misleading here. All that is needed is to repackage or rebuild (update) the IPS package for mkdocs. The version can remain 1.0.4 but the IPS package should be rebuilt with python 3 instead of python 2.7.
I occasionely use the IPS mkdocs package on OpenIndiana as the documentation website explains that also other platforms such as Linux can be used to author documentation content : see
So I think it is possible to stay / stick with mkdocs 1.0.4 and simply adapt / rebuild for a newer python version.
from oi-docs.
Also the IPS mkdocs package itself could simply be removed from the IPS repository as it is not so difficult to simply follow the "http://docs.openindiana.org/contrib/getting-started/" instructions using "pip install" instead of "pkg install" for mkdocs.
from oi-docs.
I think it would anyway make sense to update the documentation to use the latest mkdocs
version maybe with a more modern theme. So they are two different issues:
- one to remove
mkdocs
fromoi-userland
(or update it), which might be created onoi-userland
repo? - one to keep the
mkdocs
updates for the documentation itself?
from oi-docs.
My understanding is the same as @cstes. It makes sense to update the IPS package to a newer version, but this is unrelated to Python 2 removal, as the existing version doesn't require it. This is also unrelated to this repo. Personally, I also don't see why pip packages should be part of the IPS repository at all if they can be installed using pip
in OI - what benefit does this provide vs the associated maintenance cost.
None of this detracts from the benefits of upgrading the docs to use a newer MkDocs and a better theme. I'm unsure if MkDocs material is the right theme for this though as it has a problem with the PDFs (see PR comments). I'll have a look at some other themes to see if we can avoid the problems with MkDocs Material.
from oi-docs.
For the userland package my vote goes towards using pip and updating the documentation. Best we open a ticket on the issue tracker in the opeindiana project. It is what was used for a long time. I see @cstes already did that :) https://www.illumos.org/issues/14791
For the theme upgrade I am curious if the Solar
or Spacelab
theme also have that problem?
from oi-docs.
It is an easier migration if the spacelab theme is continued. The changes required are quite simple, I described them in this comment on the PR. With a few other style tweaks it is possible to retain much the same look and feel as the current docs site. The only difference is a slightly larger font size.
The MkDocs Material PR is now passing and the PDF issues are resolved. It will be up for the community to decide if they wish to move to it. Overall the feel of MkDocs Material is more modern, but I'm not sure if that's what we want for OI. The navigation doesn't use drop downs which is a change compared to the current docs.
from oi-docs.
If people are happy with the look of Material I am not against it. Especially if it fills all features.
from oi-docs.
Related Issues (20)
- dd command on OSX does not have "status" operand
- Text installer limiting domainname to 15c HOT 1
- Wrong formatting in `docs/dev/userland.md`
- Problems with makepdf.sh and general suitability of docs for PDF conversion HOT 4
- Approach for Adding Pull Request & PDF Build support to GitHub Actions HOT 5
- Splitting existing pages into multiple pages HOT 1
- OSDisc.com has closed, remove mentions from the documentation HOT 1
- Typos in the "Storage Archive Manager handbook" (samqfs.md)
- Transition of docs site to production
- Update the docs to reflect the new method for creating USB flash drives HOT 1
- Update docs to reflect the new desktop and desktop manager, etc.
- Move notes section of docs site to the wiki HOT 1
- Add a separate page to the contrib section titled - Working with GIT HOT 7
- Update site parameters per changes in mkdocs 0.16 HOT 5
- SMF documentation HOT 3
- Remove sudo from examples HOT 4
- Document zpool installation HOT 4
- Document zone-proxyd HOT 1
- No docs on how to simply connect through PPPoE to my isp HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from oi-docs.