Details

    • Rank:
      49111

      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.

        Issue Links

          Activity

          Hide
          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
          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
          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
          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
          David Scotson added a comment -

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

          Show
          David Scotson added a comment - Link to YUI shifter bug in case they've already written npm documentation for Moodle.
          Hide
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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
          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 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 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
          Jason Fowler added a comment -

          Suggestions integrated now Damyon.

          Show
          Jason Fowler added a comment - Suggestions integrated now Damyon.
          Hide
          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
          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
          Jason Fowler added a comment -

          Done.

          Show
          Jason Fowler added a comment - Done.
          Hide
          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
          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 Wiese added a comment -

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

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

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

          Show
          Jason Fowler added a comment - is there anything I need to do to get this moving?
          Hide
          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 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 Wiese added a comment -

          (Rebasing and rechecking the docs now)

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

          Integrated, thanks!

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

          passed...or it had not been integrated.

          Show
          Eloy Lafuente (stronk7) added a comment - passed...or it had not been integrated.
          Hide
          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
          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: