Details

    • Type: Sub-task
    • Status: Closed
    • Priority: Blocker
    • Resolution: Fixed
    • Affects Version/s: 2.5
    • Fix Version/s: 2.5
    • Component/s: Themes
    • Labels:

      Description

      Following on from MDL-38906, I think /theme/bootstrap/less/README does not currently make it easy for anyone to get up to speed on getting 'less' working.

      Please make it really simple for anyone with a Mac, Windows or Linux machine to get up and running with this.

      We also need a good page in Moodle Docs describing the whole process of editing bootstrap CSS, the paradigm and the conventions as well.

        Gliffy Diagrams

          Issue Links

            Activity

            Hide
            dougiamas Martin Dougiamas added a comment - - edited

            For reference to get this started I did this on my Mac:

            1) Install MacPorts on Mac OS X. If you use a different package manager some install commands will vary.

            2) Install NPM

            • port install npm
            • rehash

            3) Download https://github.com/twitter/recess/archive/master.zip and unzip it, then cd into the directory.

            4) Install recess

            • npm install recess -g
            • rehash

            5) Actually process the Moodle CSS files.

            • cd /web/master/theme/bootstrap/less
            • recess --compile --compress moodle.less > new.css
            • mv new.css ../style/generated.css
            Show
            dougiamas Martin Dougiamas added a comment - - edited For reference to get this started I did this on my Mac: 1) Install MacPorts on Mac OS X. If you use a different package manager some install commands will vary. 2) Install NPM port install npm rehash 3) Download https://github.com/twitter/recess/archive/master.zip and unzip it, then cd into the directory. 4) Install recess npm install recess -g rehash 5) Actually process the Moodle CSS files. cd /web/master/theme/bootstrap/less recess --compile --compress moodle.less > new.css mv new.css ../style/generated.css
            Hide
            bawjaws David Scotson added a comment -

            I'm on Ubuntu but I don't think step 3 is necessary. npm is like apt-get so if you ask it to "npm install recess -g" it should go out and do everything it needs to do on the network.

            Maybe some people could try the GUIs and report back which works best for them:

            https://github.com/cloudhead/less.js/wiki/GUI-compilers-that-use-LESS.js

            I believe that npm is also used by YUI Shifter, and I believe that's part of Moodle now (or just proposed?) for doing roughly the same thing to javascript as less does to CSS so maybe they could share some installation documentation within Moodle:

            http://yui.github.io/shifter/

            Show
            bawjaws David Scotson added a comment - I'm on Ubuntu but I don't think step 3 is necessary. npm is like apt-get so if you ask it to "npm install recess -g" it should go out and do everything it needs to do on the network. Maybe some people could try the GUIs and report back which works best for them: https://github.com/cloudhead/less.js/wiki/GUI-compilers-that-use-LESS.js I believe that npm is also used by YUI Shifter, and I believe that's part of Moodle now (or just proposed?) for doing roughly the same thing to javascript as less does to CSS so maybe they could share some installation documentation within Moodle: http://yui.github.io/shifter/
            Hide
            bawjaws David Scotson added a comment -

            Link to YUI shifter bug in case they've already written npm documentation for Moodle.

            Show
            bawjaws David Scotson added a comment - Link to YUI shifter bug in case they've already written npm documentation for Moodle.
            Hide
            dobedobedoh Andrew Nicols added a comment -

            Shifter is also an NPM module, as are jshint and yuidoc.

            I'm working on a wrapper which I hope to submit to the npm repo - mdl:

            https://github.com/andrewnicols/mdl.git

            sudo npm install git+https://github.com/andrewnicols/mdl.git -g

            It currently only wraps shifter, but it could be made to wrap less too if you can tell me how you'd like it to work. At present, it supplies certain defaults to shifter so you can run:

            // basic operation
            // By default this runs shifter --walk --recursive --lint config --clean
            mdl -s
            // watch
            mdl -s --watch

            It will automatically detect if you're in a src directory or a module directory and change the options to shifter accordingly.

            The idea behind mdl is to provide a simple npm module to install which installs all of the modules that we need for moodle in a single NPM package.

            Show
            dobedobedoh Andrew Nicols added a comment - Shifter is also an NPM module, as are jshint and yuidoc. I'm working on a wrapper which I hope to submit to the npm repo - mdl: https://github.com/andrewnicols/mdl.git sudo npm install git+ https://github.com/andrewnicols/mdl.git -g It currently only wraps shifter, but it could be made to wrap less too if you can tell me how you'd like it to work. At present, it supplies certain defaults to shifter so you can run: // basic operation // By default this runs shifter --walk --recursive --lint config --clean mdl -s // watch mdl -s --watch It will automatically detect if you're in a src directory or a module directory and change the options to shifter accordingly. The idea behind mdl is to provide a simple npm module to install which installs all of the modules that we need for moodle in a single NPM package.
            Hide
            dobedobedoh Andrew Nicols added a comment -

            Martin, there should be no need to downoad recess, it should be as David suggests:

            • Install npm (I use homebrew, but macports, ubuntu, the Mac OS Node.js Package includes npm too)
            • npm install recess -g
            Show
            dobedobedoh Andrew Nicols added a comment - Martin, there should be no need to downoad recess, it should be as David suggests: Install npm (I use homebrew, but macports, ubuntu, the Mac OS Node.js Package includes npm too) npm install recess -g
            Hide
            dougiamas Martin Dougiamas added a comment -

            Well, that was a direct result of me trying to follow the README, case in point.

            We need clear step-by-step recipes for all platforms here.

            Show
            dougiamas Martin Dougiamas added a comment - Well, that was a direct result of me trying to follow the README, case in point. We need clear step-by-step recipes for all platforms here.
            Hide
            bawjaws David Scotson added a comment -

            A quick but very minor improvement would be to add a marker to the link in the readme so it is "https://github.com/twitter/recess#installation" so people don't have to scroll all the way down to see the important bit. But you couldn't really get much terser than their instructions:

            "To install recess you need both node and npm installed.

            $ npm install recess -g"

            But Andrew's idea of it getting pulled in by installing a mdl package seems like a very good idea. Though someone still needs to document the installing node and npm steps for developers on Mac OS X and Windows. (Though quickly looking into it they both seem to get installed by the node installer which has standard installers for various platforms).

            Show
            bawjaws David Scotson added a comment - A quick but very minor improvement would be to add a marker to the link in the readme so it is "https://github.com/twitter/recess#installation" so people don't have to scroll all the way down to see the important bit. But you couldn't really get much terser than their instructions: "To install recess you need both node and npm installed. $ npm install recess -g" But Andrew's idea of it getting pulled in by installing a mdl package seems like a very good idea. Though someone still needs to document the installing node and npm steps for developers on Mac OS X and Windows. (Though quickly looking into it they both seem to get installed by the node installer which has standard installers for various platforms).
            Hide
            dobedobedoh Andrew Nicols added a comment - - edited

            I've published mdl to the npm repository. You can now install it with:

            # sudo npm install mdl -g
            

            I'm currently writing unit tests for the content that's there, and once I've got the bugs ironed out, I'll look at improving docs and adding options for recess and friends.

            Show
            dobedobedoh Andrew Nicols added a comment - - edited I've published mdl to the npm repository. You can now install it with: # sudo npm install mdl -g I'm currently writing unit tests for the content that's there, and once I've got the bugs ironed out, I'll look at improving docs and adding options for recess and friends.
            Hide
            phalacee Jason Fowler added a comment -

            I have written the doc page. Is there anything I have missed? Following the commands listed there I have been able to install and compile the LESS for the bootstrap theme.

            Show
            phalacee Jason Fowler added a comment - I have written the doc page. Is there anything I have missed? Following the commands listed there I have been able to install and compile the LESS for the bootstrap theme.
            Hide
            dougiamas Martin Dougiamas added a comment -

            "We also need a good page in Moodle Docs describing the whole process of editing bootstrap CSS, the paradigm and the conventions as well." probably http://docs.moodle.org/dev/Bootstrap

            In addition, Jason can you prepare a patch to nicely update /theme/bootstrap/less/README with simpler content that send people to http://docs.moodle.org/dev/LESS and http://docs.moodle.org/dev/Bootstrap ?

            Show
            dougiamas Martin Dougiamas added a comment - "We also need a good page in Moodle Docs describing the whole process of editing bootstrap CSS, the paradigm and the conventions as well." probably http://docs.moodle.org/dev/Bootstrap In addition, Jason can you prepare a patch to nicely update /theme/bootstrap/less/README with simpler content that send people to http://docs.moodle.org/dev/LESS and http://docs.moodle.org/dev/Bootstrap ?
            Hide
            phalacee Jason Fowler added a comment -

            I've pushed the patch. Not sure if I am the best person to be writing something about the conventions, process and paradigm of bootstrap CSS editing, but if no one is able to do it, I will make a start on it.

            Show
            phalacee Jason Fowler added a comment - I've pushed the patch. Not sure if I am the best person to be writing something about the conventions, process and paradigm of bootstrap CSS editing, but if no one is able to do it, I will make a start on it.
            Hide
            bawjaws David Scotson added a comment -

            I made a couple of minor additions to the LESS wiki page, and using it as a template started off the Bootstrap one too.

            Show
            bawjaws David Scotson added a comment - I made a couple of minor additions to the LESS wiki page, and using it as a template started off the Bootstrap one too.
            Hide
            poltawski Dan Poltawski added a comment -

            The main moodle.git repository has just been updated with latest weekly modifications. You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

            TIA and ciao

            Show
            poltawski Dan Poltawski added a comment - The main moodle.git repository has just been updated with latest weekly modifications. You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week. TIA and ciao
            Hide
            damyon Damyon Wiese added a comment -

            Hi Jason,

            This new version does give you the link to the less docs so people can find out how to use it (good).

            But it removes all instructions for what to do with less once it's installed (bad).

            It should contain all steps required to change the CSS e.g.

            1. Make edits to the less files in the theme/bootstrap/less folder.
            2. Compile the less files into css files:
            (insert compile instructions here)
            3. Clear caches/reload page to see changes.

            Right now the compile instructions are:

            > recess --compile --compress moodle.less > ../style/generated.css
            > recess --compile --compress editor.less > ../style/editor.css

            We may change this in future (use lessc instead of recess) but if we do we will need to update this readme anyway.

            Thanks!

            Show
            damyon Damyon Wiese added a comment - Hi Jason, This new version does give you the link to the less docs so people can find out how to use it (good). But it removes all instructions for what to do with less once it's installed (bad). It should contain all steps required to change the CSS e.g. 1. Make edits to the less files in the theme/bootstrap/less folder. 2. Compile the less files into css files: (insert compile instructions here) 3. Clear caches/reload page to see changes. Right now the compile instructions are: > recess --compile --compress moodle.less > ../style/generated.css > recess --compile --compress editor.less > ../style/editor.css We may change this in future (use lessc instead of recess) but if we do we will need to update this readme anyway. Thanks!
            Hide
            phalacee Jason Fowler added a comment -

            Suggestions integrated now Damyon.

            Show
            phalacee Jason Fowler added a comment - Suggestions integrated now Damyon.
            Hide
            dougiamas Martin Dougiamas added a comment -

            Jason after linking to the docs, you should also mention that recess is the official tool (right now) to developers to use for /theme/bootstrap specifically, because various LESS tools can give slightly different results in the generated CSS, and then give the recommended command lines to use.

            Might also be worth suggesting at the end that all new commits to LESS files in this theme should include an updated generated.css.

            Show
            dougiamas Martin Dougiamas added a comment - Jason after linking to the docs, you should also mention that recess is the official tool (right now) to developers to use for /theme/bootstrap specifically, because various LESS tools can give slightly different results in the generated CSS, and then give the recommended command lines to use. Might also be worth suggesting at the end that all new commits to LESS files in this theme should include an updated generated.css.
            Hide
            phalacee Jason Fowler added a comment -

            Done.

            Show
            phalacee Jason Fowler added a comment - Done.
            Hide
            poltawski Dan Poltawski added a comment -

            Hi,

            I think that it might be good to pause on this one until we've decided what to do about MDL-39278.

            Show
            poltawski Dan Poltawski added a comment - Hi, I think that it might be good to pause on this one until we've decided what to do about MDL-39278 .
            Hide
            damyon Damyon Wiese added a comment -

            This has integration_held anyway - but I just rebased it to stop it blocking MDL-39341.

            Show
            damyon Damyon Wiese added a comment - This has integration_held anyway - but I just rebased it to stop it blocking MDL-39341 .
            Hide
            phalacee Jason Fowler added a comment -

            is there anything I need to do to get this moving?

            Show
            phalacee Jason Fowler added a comment - is there anything I need to do to get this moving?
            Hide
            damyon Damyon Wiese added a comment -

            Removing integration_held as the decisions blocking this have been made and patches integrated (theme renamed, generated.css renamed to moodle.css and we are sticking to recess for now).

            Show
            damyon Damyon Wiese added a comment - Removing integration_held as the decisions blocking this have been made and patches integrated (theme renamed, generated.css renamed to moodle.css and we are sticking to recess for now).
            Hide
            damyon Damyon Wiese added a comment -

            (Rebasing and rechecking the docs now)

            Show
            damyon Damyon Wiese added a comment - (Rebasing and rechecking the docs now)
            Hide
            stronk7 Eloy Lafuente (stronk7) added a comment -

            Integrated, thanks!

            Show
            stronk7 Eloy Lafuente (stronk7) added a comment - Integrated, thanks!
            Hide
            stronk7 Eloy Lafuente (stronk7) added a comment -

            passed...or it had not been integrated.

            Show
            stronk7 Eloy Lafuente (stronk7) added a comment - passed...or it had not been integrated.
            Hide
            stronk7 Eloy Lafuente (stronk7) added a comment -

            Did you think this day was not going to arrive ever?

            Your patience has been rewarded, yay, sent upstream, thanks!

            Closing...ciao

            Show
            stronk7 Eloy Lafuente (stronk7) added a comment - Did you think this day was not going to arrive ever? Your patience has been rewarded, yay, sent upstream, thanks! Closing...ciao

              People

              • Votes:
                0 Vote for this issue
                Watchers:
                8 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Fix Release Date:
                  14/May/13