@Wayne-Workman Just thought you’d appreciate this.
I added a video from the channel to the snapin management page https://fogproject.readthedocs.io/en/latest/management/index.html#snapin-management

@Sebastian-Roth @Jurgen-Goedbloed
I partly agree.
I’m mostly using the move to get used to rst rather than read through every single line to update as I go. I’ll try to adopt this mentality as a focus though, maybe that’s a better way anyway.

But as for screenshots see my slack message. If we use a universal image definition file we can easily update screenshots in one place as the ui changes, which I believe will work very well with the versioning. Then once all is moved over we mark it as a release of ‘pre 1.5.9’ and then update all the rest and release as 1.5.9. Maybe I’m being overly optimistic about how fast it’ll be converted though. There are a lot of sections in that wiki beyond the top level.

Well I found one video converter that worked. But it was just the trial of it so I only got half of the video. They want $45 though.
https://www.faasoft.com/video-converter.html

Not sure if that’s worth it for the flash videos of the pre 1.0 fog gui.

@Wayne-Workman said in Improve documentation:

@JJ-Fullmer can they be converted to something YouTube supports? (as opposed to re-recording)

We can put them on the FOG Project Videos YouTube channel. https://www.youtube.com/channel/UCrvOQPcm1SDIfIrzWZ9K3bA/videos

I think this would be an excellent method, gives us extra search visibility too.

@Sebastian-Roth Good point on the gif. I was just thinking of what I’ve seen in other documentation recently. It’s cool for showing how quick and easy some things are but pause buttons are nice.

Read-the-docs has a youtube video embedded in their docs so I took that as an example and did a test with a random youtube video from our channel
https://fogproject.readthedocs.io/en/latest/management/index.html#hosts

Looks good to me.

I am having trouble getting the swf converted though. When I run it through handbrake or any online convert tool it comes out as a jumbled mess. It’s also a video showing the 0.12 fog gui. Maybe it’s not worth it, I very much doubt anyone uses that version anymore.

@Sebastian-Roth @Wayne-Workman @Jurgen-Goedbloed
So I’m going through the management section of the wiki, trying to do one page/section a day converting them to the new one. Going back through and updating them will be a separate thing I think.
There are some old flash video tutorials hosted in places like http://freeghost.sourceforge.net/videotutorials/hostinfo.html

Do we want to recreate these in a newer not about to be depreciated format? And with the new gui?
We could also just host them in github, especially for ones that don’t require sound and can just be .gif files.

For now I can just embed the old links, but especially these flash ones probably need to be updated or removed, we should just have a standard as we migrate I think. There’s also the factor that the fog gui will change again in 1.6.

So you’re wanting them to boot to the network and then to a different fog menu then the default?

Have you accomplished this outside of the api? i.e in the fog gui anywhere?

I’m just not clear on what you’re trying to set so it’s hard to say yes/no on if it’s something the API can do.

@Sebastian-Roth @Jurgen-Goedbloed
I believe that fogproject uses cloudflare. There’s a note about using cloudflare dns in the readthedocs docs.
https://docs.readthedocs.io/en/stable/custom_domains.html?highlight=domains#notes-for-cloudflare-dns-users

Doesn’t look like we’re getting that same error as described in their documentation but may still be related.

I think that reverseproxy might be what Joe set up 3 years ago but it looks like that feature is depreciated. https://docs.readthedocs.io/en/stable/custom_domains.html?highlight=domains#proxy-ssl

@Jurgen-Goedbloed
Are you able to see the built readthedocs page?
I’m having trouble getting it to build locally to see what it’s going to look like and when I go to docs.fogproject.org I get a 403 error. I think that @Joe-Schmitt may have set some security up on that page on the fogproject domain while it was to be under construction. Maybe we should host it on the readthedocs domain until we get that figured out? That’s a setting in the readthedocs project that I can’t access.

edit:
Figured out my build problems, so can at least browse it locally. Updated the readme with build instructions and added a make.ps1 for easier building.

@Sebastian-Roth I just read through that and I see his points but it’s from 4 years ago. From my experience with markdown commonmark is now widely used. Both sphinx and mkdocs use commonmark.
However, considering it sounds like we want the easily navigable versions, sphinx may be the way to go as mkdocs in readthedocs only has one theme that shows the readthedocs version dropdown (I messed with a bunch of themes yesterday). Granted sphinx can be configured to use markdown, but I suppose I can learn another documentation language.

@Jurgen-Goedbloed
I would actually strongly suggest we use mkdocs instead of sphinx.
mkdocs works better with markdown from what I’ve read and experienced and it’s a lot easier to setup and learn.
Considering the forum uses markdown, the existing wiki uses markdown, I think it would be a better option for the project.
Markdown is also a lot easier to learn and to write and I feel like it would make it a lot easier for future maintainers to pick up and run with.

This module appears to have gained some popularity…

Maybe I need to find some time to do more updating.

@Sebastian-Roth and @Jurgen-Goedbloed Could I also be added as a maintainer. I would love to help with this project.
Maybe we make some github issues for what documents need creating and or copy pasting and divide and conquer?

@Sebastian-Roth
Just gave this a test
I’m on fog 1.5.9.3
I’m using bzImage 5.6.18
I set a host to use the init you shared.

I had previously imaged this machine on the init that came with 1.5.9.3/1.5.9.2 and it imaged in 4 min 33 secs and when I watched the speed it was around 10-11 GB/min. But I wasn’t babysitting the speed, it probably slowed down a bit when I wasn’t looking based on the results below.

Same image on the new init didn’t appear to go much faster but did stay stable around 11-12 GB/min but it actually finished in 2 min 38 secs. So It almost cut the time in half.

So, I didn’t get to see the super fast 20+ GiB/min speed again, but it did finish in about half the time.

Edit

I also noticed it now shows speed in GB/min instead of GiB/min. Not that big a scale change, but something I noticed. I also deployed the image on the machine one more time, this time without being connected to a small desktop switch and got the exact same 2:38 deploy time.

Other Edit

I also noticed that I too don’t have any 2.89 partclone images to test. Mine are all 3.13 I’m pretty sure.

For the FogApi powershell module I’m using read the docs with mkdocs.
You can see the simple .readthedocs.yml and mkdocs.yml config files in my repo for it here https://github.com/darksidemilk/FogApi
The published version is here https://fogapi.readthedocs.io/en/latest/

Granted, documenting a powershell module is a bit simpler since it’s mostly documenting the functions and what they do and can be generated from comment blocks in-line in the code.

I think readthedocs requires (or is at least by default designed) to have the docs in the same repo to help maintain versions. I don’t have versioning setup though. There’s a page for setting up based on branches and I believe releases and tags as well. I believe it could still be done in a separate repo though, might just require more effort to link versions. Or it could be easier cause you just create a new version each time a version of fog is released and whatever the documentation said at that point is the documentation for that version.

There is also githubpages as a similar option, I found readthedocs a bit easier for my purposes.

I also remember @Joe-Schmitt setting up readthedocs.io for fog-too I think. That’s how I knew what readthedocs was when I wanted to make public documentation for my powershell code.

I would love to help out with getting this setup and some things documented.

Maybe we could have something that grabs stuff from the forums, or maybe just a label/tag we can report against to periodically go through and add to documentation

@Tom-Elliott no worries, a mistake anyone could make.

@Sebastian-Roth I will update my install shortly and re-image one of the machines. Will this also change my kernel? Will I need to remake that change for the surface ethernet adapter?

@Tom-Elliott @Sebastian-Roth @george1421

I gave something else a try. I looked at the commits included in the dev_branch since 1.5.9 and found that Tom had added the machine details array in the taskqueue.class.php file.

First thing I tried was adding a primary user to the host, in case that being empty was somehow a problem. No dice.

Looking at it, it’s just a prettier more informative email array. But the parameters in that object must be used somewhere else, because I reverted the file to its last commit (made a .old version of it on my server, made a new version of it with the previous version’s contents) just to see if that change maybe broke something.

My debug task was waiting for me to hit enter at another updating database attempt, so I hit enter, and viola!

So now we gotta figure out why in the world that change in the email sent would break the database update to say the task is completed.

edit:
I debugged it a bit further. Restored the newer version of the file and started commenting things out one at a time to confirm the problem.

The code here is where the problem lies (line 293-315 of taskqueue.class.php found at https://github.com/FOGProject/fogproject/blob/99bb17b168e929796a8d76526f73bcfdac11bb4b/packages/web/lib/reg-task/taskqueue.class.php)

$Inventory = self::$Host->get('inventory');
        $mac = self::$Host->get('mac')->__toString();
        $ImageName = $this->Task->getImage()->get('name');
        $ImageStartTime = self::niceDate($this->Task->get('checkInTime'));
        $ImageEndTime = self::niceDate();
        $duration = self::diff($ImageStartTime, $ImageEndTime);
        $Snapins = implode(',', (array)$SnapinNames);
        $email = array(
            sprintf("%s:-\n", _('Machine Details')) => '',
            sprintf("\n%s: ", _('Host Name')) => self::$Host->get('name'),
            sprintf("\n%s: ", _('Computer Model')) => $Inventory->get('sysproduct'),
            sprintf("\n%s: ", _('Serial Number')) => $Inventory->get('sysserial'),
            sprintf("\n%s: ", _('MAC Address')) => $mac,
            "\n" => '',
            sprintf("\n%s: ", _('Image Used')) => $ImageName,
            sprintf("\n%s: ", _('Snapin Used')) => $Snapins,
            "\n" => '',
            sprintf("\n%s: ", _('Imaged By')) => $engineer,
            sprintf("\n%s: ", _('Imaged For')) => $primaryUser,
            sprintf("\n%s: ", _('Imaging Started')) => $ImageStartTime,
            sprintf("\n%s: ", _('Imaging Completed')) => $ImageEndTime,
            sprintf("\n%s: ", _('Imaging Duration')) => $duration
        );

If I comment out the last 3 pieces of the array and try again, the database updates and all is well again

$Inventory = self::$Host->get('inventory');
        $mac = self::$Host->get('mac')->__toString();
        $ImageName = $this->Task->getImage()->get('name');
        $ImageStartTime = self::niceDate($this->Task->get('checkInTime'));
        $ImageEndTime = self::niceDate();
        $duration = self::diff($ImageStartTime, $ImageEndTime);
        $Snapins = implode(',', (array)$SnapinNames);
        $email = array(
            sprintf("%s:-\n", _('Machine Details')) => '',
            sprintf("\n%s: ", _('Host Name')) => self::$Host->get('name'),
            sprintf("\n%s: ", _('Computer Model')) => $Inventory->get('sysproduct'),
            sprintf("\n%s: ", _('Serial Number')) => $Inventory->get('sysserial'),
            sprintf("\n%s: ", _('MAC Address')) => $mac,
            "\n" => '',
            sprintf("\n%s: ", _('Image Used')) => $ImageName,
            sprintf("\n%s: ", _('Snapin Used')) => $Snapins,
            "\n" => '',
            sprintf("\n%s: ", _('Imaged By')) => $engineer,
            sprintf("\n%s: ", _('Imaged For')) => $primaryUser
            //sprintf("\n%s: ", _('Imaging Started')) => $ImageStartTime,
            //sprintf("\n%s: ", _('Imaging Completed')) => $ImageEndTime,
            //sprintf("\n%s: ", _('Imaging Duration')) => $duration
        );

@Sebastian-Roth @george1421
Ran the debug task.
It gets through everything normal all the way up to Task Complete
then it says
Updating Database.........................Failed
Then it repeats the Error Returned: Machine Details:- repeatedly. (It’s hard to count them with shift+ page up/page down but I believe it’s about 10 retries for updating the database if that helps to find where this is happening in the code)

@Sebastian-Roth Another thing I just noticed is that the debug mode loaded from the main server (i.e. the task in the gui showed ‘working with fogServer’) But the other deploy task was working with my storage node

edit: This is probably nothing, the error happened in both cases.

@Sebastian-Roth The same errors are happening on the other machine =(
What’s odd is that it’s claiming to be a database issue, but I also am adding the hosts through the pxe menu and they’re getting added to the database just fine.

@Sebastian-Roth I waited until just now and it got into the debug console. I’ve never seen it take 7 minutes to load the init. (full discolsure, I wasn’t watching it the whole time and it may have rebooted itself and worked the second time around)
It also started working as soon as I started deploying on another machine. Gonna wait to see if the other machine gets through without error before starting any debugging. Are there any debug commands that would help in troubleshooting this?