Comments (9)
Old versions are not supported, so there is no reason to keep old information around. If someday we have a stable version and a development version, then perhaps implementing something like this would be worthwhile.
from ev3dev.github.io.
Yep, this would mainly be for whenever "ev3dev stable" happens. I'm just trying to document it so that there is a centralized set of desired features.
from ev3dev.github.io.
I'm now taking a closer look at this to see how we can make this a reality, with planned ev3dev-stretch work on the horizon and multiple kernel versions to maintain as a result.
We have an existing tab-based mechanism for different versions of the same content. We use the tabs mainly for client OSes currently, where sections of instructions (or whole pages) are dependent on the OS that the user chooses. We now want to add the ability to switch between documentation versions, so that you can view documentation for ev3dev-stretch or ev3dev-jessie interchangeably. This is undoubtedly going to stretch (get it? stretch?) the limits of vanilla Jekyll, but I suspect we can still do it in a user-friendly manner if we design it properly.
I don't have a concrete design yet, however I do have some thoughts and goals:
- A system similar to what I described in #309 seems like a good starting point.
- Tabs are not an option.
- A banner below the nav bar would be nice.
- We should aim to integrate this with our OS-specific selection mechanism.
- We need to decide on a scope. Do we want to be able to version tutorials? Landing pages?
- We do not want to load multiple versions of a page into memory unless required.
- This system should handle whole-page versioning as well as small section versioning. These two functions should look the same to the user, even if they're different internally.
- We need to decide the extent to which we support JavaScript-less browsers.
- We should look into using Angular or another similar framework to lessen the use of JQuery-based HTML construction.
I'm working on a solution that addresses these points while seriously considering the technical side of the final result.
from ev3dev.github.io.
May be something similar to what readthedocs.org does? They have a small floating button in the bottom right corner which you can use to select version of the documentation. See example here: http://python-ev3dev.readthedocs.io/en/latest/
from ev3dev.github.io.
Good thinking; I hadn't considered that example. The technical side of such a design would be tough with Jekyll, but it really won't get easier with any other design 😆
I'm imagining that something similar to the readthedocs.org control with segments for each option (OS, version, etc.) might work well UX-wise.
from ev3dev.github.io.
I agree with Denis - maybe start a branch for documenting the new version and generate each branch as its own sub site - that makes it easier to merge commits across the branches too.
from ev3dev.github.io.
This is where it gets tricky 😉 This repo includes all the configuration, styles and general content (e.g. news and homepage) that really should be universal and are expected to have a single "master" copy. My worry with branching is that we'd end up with style and documentation modifications mixed in together, and then sorting out the mess would be near-impossible.
On the other hand, having two or more copies of the same file (one for each combination of ev3dev version and client OS) in the same repo also seems rather ugly, so I am not ready to go full-on down that route. Submodules seem like they may offer a nice solution, but I'm not sure exactly how or even whether they would work on GitHub Pages.
from ev3dev.github.io.
We need to decide on a scope. Do we want to be able to version tutorials? Landing pages?
I suggest everything under docs/
and nothing else.
I like the idea of basically namespacing the url, like /docs/ev3dev-jesse/ev3/windows/getting-started
.
I think between Jekyll's dynamic include (variable as file name) and relative include features we can make it happen with minimal duplication.
Multiple repositories is actually a possibility as well. The way GitHub pages is setup, there are two types of repositories. One for organizations and one for projects. Project pages actually show up as a subdirectory of the organization page. For example if you visit http://www.ev3dev.org/grx, you will find the docs served up by https://github.com/ev3dev/grx/tree/gh-pages. It is not quite ideal as it would require one GitHub repository per folder and you only get one folder level (e.g. you couldn't have multiple repositories hosted under /docs
).
from ev3dev.github.io.
I like the idea of basically namespacing the url, like /docs/ev3dev-jesse/ev3/windows/getting-started .
The issue I have with that is that "namespacing" the URL leaves you with no canonical version of the page. If we want to point someone to the guide without knowing their OS, we'd need to manually create a page with links to the various versions. And we'd need to do that for every page and every combination of variables 😢 I think that the biggest limiting factor here is that we can't dynamically create pages. Maybe we need some sort of a preprocessor... but I really don't want to start strapping additional stuff to our build just to achieve a suboptimal experience.
I think between Jekyll's dynamic include (variable as file name) and relative include features we can make it happen with minimal duplication.
I don't think the relative one will help us, because it requires that the template is within the file's parent directory. We can probably rig something together with the normal includes, but our template directory is going to get really full! 😁
Multiple repositories is actually a possibility as well. The way GitHub pages is setup, there are two types of repositories. One for organizations and one for projects. Project pages actually show up as a subdirectory of the organization page. For example if you visit http://www.ev3dev.org/grx, you will find the docs served up by https://github.com/ev3dev/grx/tree/gh-pages. It is not quite ideal as it would require one GitHub repository per folder and you only get one folder level (e.g. you couldn't have multiple repositories hosted under /docs ).
We have an issue here with search capability. For our search mechanism to work, every page must be known at build time. We should be able to get the same effect with submodules, though.
from ev3dev.github.io.
Related Issues (20)
- Make platform comparison page discoverable HOT 1
- Local preview improperly renders newlines HOT 1
- Update PS3 gamepad tutorial for Python 3 and newer hardware HOT 2
- Consolidate breadcrumb logic and update breadcrumbs in site search
- Modify intro sentences on homepage to give a better summary
- Update WeDo 2.0 tutorial for python 3 and debian packages instead of pip HOT 1
- Broken Links HOT 10
- List the version of the linked files on the download page
- Promote the "upgrading" guide HOT 2
- Add proper descriptions for class documentation pages HOT 4
- "Getting Started" says "2GB or large" but actual download image is 3.8GB HOT 4
- Load download button styles before API responds HOT 3
- Doker/Docker-Toolbox differences with shared folders HOT 2
- Executing a Docker compiled file on the EV3 HOT 6
- How do I enter the wifi password? HOT 3
- Section "Previewing your changes online" is unclear HOT 3
- "Using Docker to Cross-Compile" tutorial refers to brickstrap HOT 2
- ev3 Buttons wait_for_bump HOT 2
- Add Prolog API to list of languages HOT 2
- Docker is not a virtual machine
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 ev3dev.github.io.