Page 1 of 2
Posted: 05 Jul 2018, 10:48
There was discussion in PRs last year about the inclusion of images in documentation- more particularly about where to host them. I will try to identify the starting point later, I am fairly sure it involved additions to the "CS Tour" documentation by Thunderforge and me.
It arose from concern about the size of images, but then extended to my concern about how to achieve consistency in style, particularly of screenshots.
Have there been any further discussrlions or decisions about these matters?
Posted: 05 Jul 2018, 11:01
Not that I'm aware of.
However... there are options for hosting images. We can setup a repo for example to handle that, but I'm not sure that sphinx supports out of tree images.
Posted: 05 Jul 2018, 12:36
We could do this:
https://stackoverflow.com/questions/263 ... -text-docu
so we can do this a few ways:
1) apart GL project/repo to host binaries (images) and link to those.
2) use an image hosting service and link to that.
3) some other method...
Posted: 05 Jul 2018, 13:10
psi29a wrote: ↑
05 Jul 2018, 12:36
2) use an image hosting service and link to that.
I think this would be best - you know, that's how e.g. Wikipedia works. Would recommend MediaGoblin
- it's free software, we could host our own instance or use an existing one.
Posted: 06 Jul 2018, 06:00
I remember the discussion and recall not coming to a decision lol.
On the subject of hosting:
At first glance, I feel like external hosting service would be best. I don't really see much benefit to having a Git*** repo containing them over an external host (just that we all have accounts already?). An external service will need to have several of us as admins so if one of us leaves or is away, we can take care of any problems. I think this is probably pretty standard on many sites so we'll just have to check some out and see what we think. My biggest concern about external sites is speed of loading in the docs. If the hosting service isn't very fast and we have several images on one page, it would be nice if it didn't take several seconds for them to all download to the client browser. If they're properly optimized this would hopefully not be an issue, but you can only compress a large image so much.
This brings me to the only other option I really see as viable, hosting within our repo. Depending on number of images we think we'll end up using, if they're properly optimized they shouldn't really take up much space. Is this really that big of an issue? Is the concern repo space or developers having to download images they don't need? Would a few images here and there really impact developers' download times? I don't really care that much one way or the other, but perhaps we can start with this if people are willing to write the docs while we find a hosting service?
On the subject of consistent style:
We need one. I would very much prefer that we don't add any effects whatsoever to the image file itself. That saves time and enforces consistency. I do like maybe a very subtle drop shadow or maybe a single pixel outline or something like that to make it pop, but I believe there are ways within Sphinx to do this. I'm pretty sure CSS3 added drop shadows so it should be trivial assuming we can add a custom style. The problem is if RTD (our docs host), which has their own overall style, would be able to use this. This is definitely something we should look into, not sure if you have any additional insight on the subject psi29a?
What's going to be difficult is maintaining consistency between screenshots. I foresee the window style of different OSs giving weird border differences for different users. Does OpenMW-CS enforce it's own window borders? We could have people request screenshots by other people with a chosen OS, but I find that to be an unacceptable solution. Regardless, we will also have to make sure people only screenshot the portion of their screen with the pertinent information. Does anyone know of any free screenshot software that you can just click on a window and it will automatically take a screenshot of just that window? That would make it very easy.
Posted: 06 Jul 2018, 07:47
We don't want to include binary data (such as images) into our source repo. It happens because they are resources for the Launcher and OpenMW-CS, but they don't change very often. We don't want people wasting time downloading files they'll never use.
When I mean apart repo, I mean a project under GitLab/OpenMW and call it openmw_doc_images or something. That's fine because that's it's purpose. It can be huge, up to 2GiB and more importantly, we can clean up after ourselves and lose history by trimming off old binaries/images. This is something we do _not_ want done in our source repo where history is important.
I'll look into the RTD thing. I think we can use our own 'template' if we wanted. I honestly think the style they have is professional and to the point.
Posted: 06 Jul 2018, 17:39
If the images are part of the documentation, why wouldn't they be versioned alongside the text?
Posted: 06 Jul 2018, 23:59
wareya wrote: ↑
06 Jul 2018, 17:39
If the images are part of the documentation, why wouldn't
they be versioned alongside the text?
Then I would suggest our documentation live outside our project source and inside it's own project repo.
Posted: 07 Jul 2018, 00:06
That option has advantages, but then when a PR adds a bunch of new settings, like shadows does, the documentation for those settings doesn't go live at the same time as the PR gets merged.
Posted: 07 Jul 2018, 09:13
Get your images merged before posting? Same problem if we used an external image hosting service... get your ducks in a row.