• Recent
  • Unsolved
  • Tags
  • Popular
  • Users
  • Groups
  • Search
  • Register
  • Login
  • Recent
  • Unsolved
  • Tags
  • Popular
  • Users
  • Groups
  • Search
  • Register
  • Login

Improve documentation

Scheduled Pinned Locked Moved
General
4
51
6.5k
Loading More Posts
  • Oldest to Newest
  • Newest to Oldest
  • Most Votes
Reply
  • Reply as topic
Log in to reply
This topic has been deleted. Only users with topic management privileges can see it.
  • ?
    A Former User
    last edited by Oct 10, 2020, 2:35 PM

    I am now working on the installation part of the manual.

    Can we agree on the starting point that, when coping things from the wiki to the new documentation that we will only focus on the current (1.5.9) version? So all parts that refer to old versions will not be copied and that we will also use screenshots of the current version. I think this will help a lot in understanding and recognition for new Fog users.

    1 Reply Last reply Reply Quote 1
    • S
      Sebastian Roth Moderator
      last edited by Oct 10, 2020, 3:29 PM

      @Jurgen-Goedbloed said in Improve documentation:

      Can we agree on the starting point that, when coping things from the wiki to the new documentation that we will only focus on the current (1.5.9) version? So all parts that refer to old versions will not be copied and that we will also use screenshots of the current version. I think this will help a lot in understanding and recognition for new Fog users.

      Absolutely I would say! We encourage people to update to the latest official version over and over in the forums. So it’s fair enough to only provide documentation for that as well.

      Web GUI issue? Please check apache error (debian/ubuntu: /var/log/apache2/error.log, centos/fedora/rhel: /var/log/httpd/error_log) and php-fpm log (/var/log/php*-fpm.log)

      Please support FOG if you like it: https://wiki.fogproject.org/wiki/index.php/Support_FOG

      J 1 Reply Last reply Oct 11, 2020, 6:28 PM Reply Quote 1
      • J
        JJ Fullmer Testers @Sebastian Roth
        last edited by Oct 11, 2020, 6:28 PM

        @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.

        Have you tried the FogApi powershell module? It's pretty cool IMHO
        https://github.com/darksidemilk/FogApi
        https://fogapi.readthedocs.io/en/latest/
        https://www.powershellgallery.com/packages/FogApi
        https://forums.fogproject.org/topic/12026/powershell-api-module

        J 1 Reply Last reply Oct 12, 2020, 7:24 PM Reply Quote 0
        • J
          JJ Fullmer Testers @JJ Fullmer
          last edited by Oct 12, 2020, 7:24 PM

          @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

          Have you tried the FogApi powershell module? It's pretty cool IMHO
          https://github.com/darksidemilk/FogApi
          https://fogapi.readthedocs.io/en/latest/
          https://www.powershellgallery.com/packages/FogApi
          https://forums.fogproject.org/topic/12026/powershell-api-module

          1 Reply Last reply Reply Quote 1
          • J
            JJ Fullmer Testers
            last edited by Oct 12, 2020, 8:15 PM

            @Sebastian-Roth @Tom-Elliott
            Am I correct in that we no longer use the mobile versions of pages and we just use responsive css to make the fog management page at least somewhat universally friendly. And that this is meant to be improved more so in the 1.6 UI?
            I’m asking in reference to converting this section https://wiki.fogproject.org/wiki/index.php?title=Managing_FOG#Mobile_Management_Interface
            I’m thinking that it could all be replaced with just a note about the page using responsive.css.

            Have you tried the FogApi powershell module? It's pretty cool IMHO
            https://github.com/darksidemilk/FogApi
            https://fogapi.readthedocs.io/en/latest/
            https://www.powershellgallery.com/packages/FogApi
            https://forums.fogproject.org/topic/12026/powershell-api-module

            1 Reply Last reply Reply Quote 0
            • J
              JJ Fullmer Testers
              last edited by Oct 15, 2020, 4:03 PM

              @Wayne-Workman Do you know if there are some orphaned wiki pages? Or rather how to find the parent of a wiki page? I’m finding links to pages like this one https://wiki.fogproject.org/wiki/index.php?title=Creating_a_Samba_Based_Printer_Store_on_FOG

              Granted this one might need a little updating, but even still I’m not sure where it’s home should be. Should this be in a Knowledge Base Section? A reference section? As far as I know, you’re the resident wiki expert so I thought you might have insights.

              Have you tried the FogApi powershell module? It's pretty cool IMHO
              https://github.com/darksidemilk/FogApi
              https://fogapi.readthedocs.io/en/latest/
              https://www.powershellgallery.com/packages/FogApi
              https://forums.fogproject.org/topic/12026/powershell-api-module

              1 Reply Last reply Reply Quote 0
              • S
                Sebastian Roth Moderator
                last edited by Oct 15, 2020, 5:08 PM

                @JJ-Fullmer Probably you’ll find a fair amount of those kind of topics in the wiki. I’d hope this is a good chance to get rid of some dated stuff as well. The one you mentioned about samba is 10 years old, talking about Ubuntu 10.04 (!) and I am not sure if people really have those kind of setups. Anyone an idea?

                Web GUI issue? Please check apache error (debian/ubuntu: /var/log/apache2/error.log, centos/fedora/rhel: /var/log/httpd/error_log) and php-fpm log (/var/log/php*-fpm.log)

                Please support FOG if you like it: https://wiki.fogproject.org/wiki/index.php/Support_FOG

                1 Reply Last reply Reply Quote 2
                • W
                  Wayne Workman
                  last edited by Wayne Workman Oct 15, 2020, 4:51 PM Oct 15, 2020, 10:37 PM

                  If you look at the history on that one, it was added by “admin” in 2010 (probably by @Chuck-Syperski). I don’t remember seeing this article before.

                  When I was doing printers with fog (which works great last I used it), I just made a share on the Windows server to hold drivers, accessible anonymously.

                  This article is newer and better suited for creating samba shares: https://wiki.fogproject.org/wiki/index.php?title=Password_Protected_Samba_Share

                  I wrote that in 2016 when there wasn’t even RHEL 8/CentOS 8, but had foresight to add the correct commands.

                  Please help us build the FOG community with everyone involved. It's not just about coding - way more we need people to test things, update documentation and most importantly work on uniting the community of people enjoying and working on FOG!
                  Daily Clean Installation Results:
                  https://fogtesting.fogproject.us/
                  FOG Reporting:
                  https://fog-external-reporting-results.fogproject.us/

                  1 Reply Last reply Reply Quote 2
                  • J
                    JJ Fullmer Testers
                    last edited by Oct 16, 2020, 8:09 PM

                    I made a draft of a top level tree

                    I think we may need subfolders beyond this rather than including everything in one sectioned out page like we’re doing for the installation and management sections.

                    2b9743e3-9261-4130-92aa-c07f518096f0-image.png

                    I’d appreciate some feedback. I was thinking 10 top level categories is a good limit, but will everything fit into these categories.
                    And then will we need to add another heading level to split out any sub categories. i.e. in the wiki there is a how-to guide section outlined like this

                    3f24852c-fd24-4e72-a314-75d25b469fe3-image.png

                    each link being an individual page. We could probably combine each of those headings into a single grouped index page the way we’re doing the current pages. But they would each have another subfolder in one of the top level folders. i.e. customization\ipxe would have an index.rst that would combine all the pages under FOG PXE/iPXE Menu

                    But we currently are breaking documents into their own rst files at the heading 2 level, but we probably don’t want a gigantic customization page even with navigation. Perhaps we have some more pages like the root index.

                    Or maybe we should just follow examples of existing pages like https://docs.readthedocs.io/en/stable/index.html and giving a bigger overview at the top level and maintain the title/sub-title level navigation sections throughout on the left panel.

                    Just trying to get this right before we’re in too deep and changing it becomes a huge pain.

                    Have you tried the FogApi powershell module? It's pretty cool IMHO
                    https://github.com/darksidemilk/FogApi
                    https://fogapi.readthedocs.io/en/latest/
                    https://www.powershellgallery.com/packages/FogApi
                    https://forums.fogproject.org/topic/12026/powershell-api-module

                    1 Reply Last reply Reply Quote 0
                    • W
                      Wayne Workman
                      last edited by Oct 17, 2020, 12:13 AM

                      Sub-folders sound fine.
                      Where might these fit in?

                      • https://wiki.fogproject.org/wiki/index.php?title=Migrate_FOG
                      • https://wiki.fogproject.org/wiki/index.php?title=Password_Central
                      • https://wiki.fogproject.org/wiki/index.php?title=.fogsettings

                      Please help us build the FOG community with everyone involved. It's not just about coding - way more we need people to test things, update documentation and most importantly work on uniting the community of people enjoying and working on FOG!
                      Daily Clean Installation Results:
                      https://fogtesting.fogproject.us/
                      FOG Reporting:
                      https://fog-external-reporting-results.fogproject.us/

                      1 Reply Last reply Reply Quote 0
                      • S
                        Sebastian Roth Moderator
                        last edited by Oct 17, 2020, 10:00 AM

                        @JJ-Fullmer said:

                        Just trying to get this right before we’re in too deep and changing it becomes a huge pain.

                        Absolutely right to think about structure before we rush into it. On the other hand it can still happen that we decide one way and figure out there is a better way later on. To get an idea on what is possible I looked through some other projects documentation (just a random search on the web) and found a couple that might help us decide.

                        • https://jupyter.readthedocs.io/en/latest/ - top bar menu for top level and side bar menu for 2nd & 3rd level plus the in page references on the right side - definitely check out the code on github as well for directory structure ideas.

                        • https://python-gitlab.readthedocs.io/en/latest/ - similar complex structure but way less clear compared to the above one I find.

                        • File and directory structure seems to be fairly clear in this project as well.

                        @Wayne-Workman said:

                        Where might these fit in?

                        • https://wiki.fogproject.org/wiki/index.php?title=Migrate_FOG
                        • https://wiki.fogproject.org/wiki/index.php?title=Password_Central
                        • https://wiki.fogproject.org/wiki/index.php?title=.fogsettings

                        I would see those three in the FAQ section, what do you think? Maybe we’d structure FAQs a bit as well so we don’t end up with a list of 50 unsorted FAQs.

                        Web GUI issue? Please check apache error (debian/ubuntu: /var/log/apache2/error.log, centos/fedora/rhel: /var/log/httpd/error_log) and php-fpm log (/var/log/php*-fpm.log)

                        Please support FOG if you like it: https://wiki.fogproject.org/wiki/index.php/Support_FOG

                        W 1 Reply Last reply Oct 17, 2020, 8:17 PM Reply Quote 0
                        • S
                          Sebastian Roth Moderator
                          last edited by Oct 17, 2020, 2:30 PM

                          The theme used by jupyter is called pydata-sphinx-theme. The more I look at it the more I like it. What do you think @JJ-Fullmer @Jurgen-Goedbloed @Wayne-Workman?

                          Web GUI issue? Please check apache error (debian/ubuntu: /var/log/apache2/error.log, centos/fedora/rhel: /var/log/httpd/error_log) and php-fpm log (/var/log/php*-fpm.log)

                          Please support FOG if you like it: https://wiki.fogproject.org/wiki/index.php/Support_FOG

                          J 3 Replies Last reply Oct 19, 2020, 2:20 PM Reply Quote 1
                          • W
                            Wayne Workman @Sebastian Roth
                            last edited by Oct 17, 2020, 8:17 PM

                            @Sebastian-Roth said in Improve documentation:

                            I would see those three in the FAQ section, what do you think?

                            I think putting them in FAQ is fine, though the ones on fogsettings and password_central seem more like documentation that frequently asked questions. migrate_fog is more like a procedural thing. Though long as they get in there somewhere, it works.

                            Please help us build the FOG community with everyone involved. It's not just about coding - way more we need people to test things, update documentation and most importantly work on uniting the community of people enjoying and working on FOG!
                            Daily Clean Installation Results:
                            https://fogtesting.fogproject.us/
                            FOG Reporting:
                            https://fog-external-reporting-results.fogproject.us/

                            1 Reply Last reply Reply Quote 0
                            • J
                              JJ Fullmer Testers @Sebastian Roth
                              last edited by Oct 19, 2020, 2:20 PM

                              @Sebastian-Roth I kind of like it, it doesn’t appear to have to think I like about the default read-the-docs theme with the expanding sidebar
                              daf6b452-82c4-45c4-bc93-a0e9bd6a43c0-image.png

                              But that example also doesn’t have a ton of section levels, so I’ll give adding it a go and see what it looks like for us. The Jupyter page seemed to be loading a bit slower than other ones, but that is probably unrelated to the theme. I mean we could also customize our own theme and make it look like for 1.6’s gui. But that could be a separate project.

                              @Wayne-Workman
                              For at least the .fogsettings page, we’ve already go that in the reference section I believe https://fogproject.readthedocs.io/en/latest/reference/index.html#the-fogsettings-file

                              I like the FSCrawler, and ansible, and readthedocs documentation tree structure layouts the best myself. Having a few very top level things to break up and organize the rest. Then it expands on down.

                              I think as long as we get the general structure agreed upon, changing up the order of things or adding new sections will be simple.

                              Have you tried the FogApi powershell module? It's pretty cool IMHO
                              https://github.com/darksidemilk/FogApi
                              https://fogapi.readthedocs.io/en/latest/
                              https://www.powershellgallery.com/packages/FogApi
                              https://forums.fogproject.org/topic/12026/powershell-api-module

                              1 Reply Last reply Reply Quote 0
                              • J
                                JJ Fullmer Testers @Sebastian Roth
                                last edited by JJ Fullmer Oct 19, 2020, 1:00 PM Oct 19, 2020, 4:26 PM

                                @Sebastian-Roth I tried to install that theme per the instructions in their git to no avail. I tried following some of the example site’s configs too and haven’t got it to work yet. I think it’s worth getting, just keeping you updated.

                                Edit

                                It wasn’t working because I had a dyslexic moment and because they were missing steps in their instructions

                                installs with pydata-sphinx-theme but then you define it as your theme with pydata_sphinx_theme those silly underscores and dashes.
                                I also had to add a html_context section and a html_theme_options sections in the conf.py. And I had to manually copy over the _templates files from the theme’s repo into our project. But I got it working. It changes things up a little bit but it’s fixable, it’s just a question of what makes the most sense.

                                There are still some kinks to work out but I think I like it.

                                It ends up looking like this

                                b2046660-0ccc-4101-b7d2-9384eac0a6be-image.png

                                a7bdeb27-2dbd-4800-bae9-c7ea48e4fc3f-image.png

                                The front page is still very much a rough draft. But we could have something like this as exists in many other pages using this theme. Note the little panels. I figure we could have links to each top level section with a brief summary of what information is in each section.

                                96a84a6e-e54c-43f5-a603-f763465d08d8-image.png

                                This also changes it from combining pages into one index to more individual pages. It can be a bit easier to navigate this way and you still keep that information grouped together nicely in this theme. This is a nice find @Sebastian-Roth. All the themes I played with outside the default removed the read-the-docs version modal. This one is pretty great

                                Have you tried the FogApi powershell module? It's pretty cool IMHO
                                https://github.com/darksidemilk/FogApi
                                https://fogapi.readthedocs.io/en/latest/
                                https://www.powershellgallery.com/packages/FogApi
                                https://forums.fogproject.org/topic/12026/powershell-api-module

                                1 Reply Last reply Reply Quote 1
                                • J
                                  JJ Fullmer Testers @Sebastian Roth
                                  last edited by Oct 19, 2020, 9:23 PM

                                  @Sebastian-Roth I’ve almost got a decent prototype of our docs with that theme live. There are some things that aren’t working and I haven’t sorted out why yet. Mainly the floating ‘what’s on this page’ on the right doesn’t seem to float when you scroll on our site. Trying to find the css or js that is missing. But other than that I like this theme. It changes our structuring a bit but makes it more flexible.

                                  Have you tried the FogApi powershell module? It's pretty cool IMHO
                                  https://github.com/darksidemilk/FogApi
                                  https://fogapi.readthedocs.io/en/latest/
                                  https://www.powershellgallery.com/packages/FogApi
                                  https://forums.fogproject.org/topic/12026/powershell-api-module

                                  1 Reply Last reply Reply Quote 0
                                  • S
                                    Sebastian Roth Moderator
                                    last edited by Oct 19, 2020, 9:32 PM

                                    @JJ-Fullmer Looks really great I find. Thanks for picking this up a working on it!

                                    Web GUI issue? Please check apache error (debian/ubuntu: /var/log/apache2/error.log, centos/fedora/rhel: /var/log/httpd/error_log) and php-fpm log (/var/log/php*-fpm.log)

                                    Please support FOG if you like it: https://wiki.fogproject.org/wiki/index.php/Support_FOG

                                    J 1 Reply Last reply Oct 23, 2020, 3:21 PM Reply Quote 0
                                    • J
                                      JJ Fullmer Testers @Sebastian Roth
                                      last edited by Oct 23, 2020, 3:21 PM

                                      @Sebastian-Roth @Jurgen-Goedbloed I have got the new theme working with scrolling toc and all. I think the top menu needs a little tlc https://fogproject.readthedocs.io

                                      Do we want to stick with this theme or revert back to the default theme, I know @Jurgen-Goedbloed mentioned he didn’t like it as much. I don’t want to go changing the readme with the structural changes if we’re not gonna stick with this theme. Personally I didn’t like it at first but it’s grown on me and it’s pretty easy to navigate.

                                      Have you tried the FogApi powershell module? It's pretty cool IMHO
                                      https://github.com/darksidemilk/FogApi
                                      https://fogapi.readthedocs.io/en/latest/
                                      https://www.powershellgallery.com/packages/FogApi
                                      https://forums.fogproject.org/topic/12026/powershell-api-module

                                      J 1 Reply Last reply Oct 26, 2020, 7:12 PM Reply Quote 1
                                      • J
                                        JJ Fullmer Testers @JJ Fullmer
                                        last edited by Oct 26, 2020, 7:12 PM

                                        The theme has been reverted for now. I have made a top level tree and structured things per the sphinx and rtd recommendations.
                                        Since it’s now following the structure it’s designed to use, switching themes down the road should be easy breezy.

                                        Have you tried the FogApi powershell module? It's pretty cool IMHO
                                        https://github.com/darksidemilk/FogApi
                                        https://fogapi.readthedocs.io/en/latest/
                                        https://www.powershellgallery.com/packages/FogApi
                                        https://forums.fogproject.org/topic/12026/powershell-api-module

                                        1 Reply Last reply Reply Quote 1
                                        • S
                                          Sebastian Roth Moderator
                                          last edited by Sebastian Roth Nov 4, 2020, 1:09 PM Nov 4, 2020, 7:08 AM

                                          @Jurgen-Goedbloed @JJ-Fullmer We have the DNS entry now. https://docs.fogproject.org/en/latest/

                                          Web GUI issue? Please check apache error (debian/ubuntu: /var/log/apache2/error.log, centos/fedora/rhel: /var/log/httpd/error_log) and php-fpm log (/var/log/php*-fpm.log)

                                          Please support FOG if you like it: https://wiki.fogproject.org/wiki/index.php/Support_FOG

                                          J 1 Reply Last reply Nov 9, 2020, 2:36 PM Reply Quote 1
                                          • 1
                                          • 2
                                          • 3
                                          • 3 / 3
                                          • First post
                                            Last post

                                          164

                                          Online

                                          12.0k

                                          Users

                                          17.3k

                                          Topics

                                          155.2k

                                          Posts
                                          Copyright © 2012-2024 FOG Project