madness 0.5.5 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6f4a303db577b3f07559d4f2089503e17cdb89d83ef78792f4d6ed2e28a8386
-  data.tar.gz: 6a37141d3f5835ce3b847a503de82e01c24dba20a65323f4cf1f9c30b5e5a0a6
+  metadata.gz: 61800bba372a7802c94d6e1b03ae7ae976a272bd46e70bcd6ee4c6840c0f99b9
+  data.tar.gz: 80b9b50292629189fb9592eff557a63aa23cf856541a174782dffc253f0c1adf
 SHA512:
-  metadata.gz: feaa75621dcf013bac0e9b63feb9a4ae06a3a6e085e2534c71099ba69d9031a44253cd545e98b7b175a769628333c9c27144293efe364822be006658e2842643
-  data.tar.gz: 5f37aada6e275be6836074ae155dfaaa8e6a4d1244600ed7e51faa62c33203fe3861b4b9963ad4c04ef2f19fb9f72de6ecb47844981dbf2d686b59513bd18643
+  metadata.gz: 7e25d76930f8ebad4bb54edeb033b0cd8fc1cd90c8455ebfbc534cd09df211c4f49b4ce616930ba2ca30dc9f7f8685f1bf12a1d541e43779071390f8fa1b0e50
+  data.tar.gz: fa5f24750e105497e026c1afe6d5ac0a5815e0db7aaf3c5aec97afbc6ac07044f6249e329b169292828543dfabe128ecb13a1862a63f6bb1a0b1a66461ff45b3

data/README.md

@@ -30,7 +30,7 @@ Table of Contents
 * [Automatic H1](#automatic-h1)
 * [Table of Contents Generation](#table-of-contents-generation)
 * [Hidden Directories](#hidden-directories)
-* [Changing Theme](#changing-theme)
+* [Customizing Theme](#customizing-theme)
 * [Docker Image](#docker-image)
 
 
@@ -53,11 +53,13 @@ searching for local, markdown based documentation directories.
 Feature Highlights
 --------------------------------------------------
 
-- Easy to use
-- Built in full text search
-- Compatible with how markdown files are displayed on GitHub andGitHub pages.
-- Configure with a configuration file or command arguments
-- Automatic generation of Table of Contents
+- Easy to use.
+- Built-in full text search.
+- Compatible with how markdown files are displayed on GitHub and GitHub pages.
+- Configure with a configuration file or command arguments.
+- Fully customizable theme.
+- Automatic generation of navigation sidebar.
+- Automatic generation of Table of Contents.
 
 
 
@@ -95,7 +97,6 @@ Example structure:
 ├── README.md
 ├── File.md
 ├── Another File.md
-├── File-with-Dashes.md
 ├── Folder
 │   ├── File.md
 │   └── image.png
@@ -125,6 +126,13 @@ highlighter: true
 line_numbers: true
 index: false
 toc: Table of Contents
+theme: _theme
+```
+
+For convenience, you can get a template config file by running:
+
+```shell
+$ madness create config
 ```
 
 
@@ -194,18 +202,45 @@ numbers (`/^[a-z_\-0-9]+$/`) will not be displayed in the navigation.
 
 
 
-Changing Theme
+Customizing Theme
 --------------------------------------------------
 
-To change the CSS of your documentation server:
+There are two ways to change how Madness looks. 
+
+
+### Option 1: Change CSS and HTML (Slim)
+
+In order to have complete control over the CSS and generated HTML, you
+can override the views and styles. Views are provided as Slim templates, 
+and CSS is provided as SCSS.
+
+Madness comes with a command that copies the default theme to a folder of
+your choice, where you can customize it to your taste. Run:
+
+```shell
+$ madness create config my_theme
+```
+
+Where `_theme` is the folder that will be created.
+
+To use the created theme, simply run Madness with the `--theme my_theme`
+option.
+
+```shell
+$ madness --theme my_theme
+```
+
+
+### Option 2: Change CSS only
+
+If you are looking to implement a more minor CSS change, follow these steps:
 
 - Create a directory named `css` in your root documentation directory.
 - Copy the [main.css][css] file to it.
 - Update it as you see fit.
 
 Note that this functionality is not guaranteed to stay as is in future 
-versions of madness, since support for themes is still not yet fully 
-implemented.
+versions of madness.
 
 
 
@@ -234,4 +269,5 @@ For more information see:
 [dockerhub]: https://hub.docker.com/r/dannyben/madness/
 [dockerfile]: https://github.com/DannyBen/docker-madness
 [css]: app/public/css/main.css
+[app]: app
 

data/lib/madness.rb

@@ -31,5 +31,6 @@ require 'madness/server'
 require 'madness/server_base'
 require 'madness/settings'
 require 'madness/table_of_contents'
+require 'madness/theme'
 require 'madness/version'
 

data/lib/madness/command_line.rb

@@ -1,3 +1,5 @@
+require 'fileutils'
+
 module Madness
 
   # Handle command line execution. Used by bin/madness.
@@ -5,28 +7,39 @@ module Madness
     include Singleton
     include Colsole
 
-    # Launch the server
+    # Process ARGV by putting it through docopt
     def execute(argv=[])
-      launch_server_with_options argv
-    end
-
-    private
-
-    # Execute the docopt engine to parse the options and then launch the
-    # server.
-    def launch_server_with_options(argv)
       doc = File.read File.expand_path('docopt.txt', __dir__)
+      
       begin
         args = Docopt.docopt(doc, argv: argv, version: VERSION)
-        set_config args
-        generate_stuff
-        launch_server unless args['--and-quit']
-
+        handle args
       rescue Docopt::Exit => e
         puts e.message
       end
     end
 
+    private
+
+    # Separate between the two main modes: Create something, or launch
+    # the server.
+    def handle(args)
+      if args['create']
+        create_config if args['config']
+        create_theme(args['FOLDER']) if args['theme']
+      else
+        launch_server_with_options args
+      end
+    end
+
+    # Execute some pre-server-launch operations if needed, and execute
+    # the server.
+    def launch_server_with_options(args)
+      set_config args
+      generate_stuff
+      launch_server unless args['--and-quit']
+    end
+
     # Launch the server, but not before doing some checks and making sure
     # we ask it to "prepare". This will set the server options such as port
     # and static files folder.
@@ -44,16 +57,17 @@ module Madness
     # Get the arguments as provided by docopt, and set them to our own
     # config object.
     def set_config(args)
-      config.path = args['PATH']   if args['PATH']
-      config.port = args['--port'] if args['--port']
-      config.bind = args['--bind'] if args['--bind']
-      config.toc  = args['--toc']  if args['--toc']
-      config.auto_h1      = false  if args['--no-auto-h1']
-      config.auto_nav     = false  if args['--no-auto-nav']
-      config.sidebar      = false  if args['--no-sidebar']
-      config.highlighter  = false  if args['--no-syntax']
-      config.line_numbers = false  if args['--no-line-numbers']
-      config.index        = true   if args['--index']
+      config.path  = args['PATH']   if args['PATH']
+      config.port  = args['--port'] if args['--port']
+      config.bind  = args['--bind'] if args['--bind']
+      config.toc   = args['--toc']  if args['--toc']
+      config.auto_h1      = false   if args['--no-auto-h1']
+      config.auto_nav     = false   if args['--no-auto-nav']
+      config.sidebar      = false   if args['--no-sidebar']
+      config.highlighter  = false   if args['--no-syntax']
+      config.line_numbers = false   if args['--no-line-numbers']
+      config.index        = true    if args['--index']
+      config.theme = File.expand_path(args['--theme'], config.path) if args['--theme']
     end
 
     # Generate index and toc, if requested by the user.
@@ -62,6 +76,26 @@ module Madness
       build_toc   if config.toc
     end
 
+    # Create config
+    def create_config
+      if File.exist? config.filename
+        say "!txtred!Abort: config file #{config.filename} already exists"
+      else
+        FileUtils.cp File.expand_path('templates/madness.yml', __dir__), config.filename
+        say "!txtgrn!Created #{config.filename} config file"
+      end
+    end
+
+    # Create theme
+    def create_theme(path)
+      if Dir.exist? path
+        say "!txtred!Abort: folder #{path} already exists"
+      else
+        FileUtils.cp_r File.expand_path('../../app', __dir__), path
+        say "!txtgrn!Created #{path} theme folder"
+      end
+    end
+
     # Say hello to everybody when the server starts, showing the known 
     # config.
     def show_status
@@ -70,7 +104,9 @@ module Madness
       say_status :listen, "#{config.bind}:#{config.port}", :txtblu
       say_status :path, File.realpath(config.path), :txtblu
       say_status :use, config.filename if config.file_exist?
-      say "-" * 40
+      say_status :theme, config.theme, :txtblu if config.theme
+
+      say "-" * 60
     end
 
     # Build the search index

data/lib/madness/docopt.txt

@@ -2,42 +2,67 @@ Madness
 
 Usage:
   madness [PATH] [options]
+  madness create config
+  madness create theme FOLDER
   madness (-h|--help|--version)
 
+Subcommands:
+  create config
+    Initialize a new default .madness.yml config file.
+
+  create theme
+    Initialize a new theme folder, based on the default theme. You can then
+    customize it to your needs and use it with --theme.
+
 Parameters:
   PATH:
     Optional path to the markdown directory.
+    (Config option: path)
 
 Options:
   -p, --port NUMBER
     Set server port number.
+    (Config option: port)
 
   -b, --bind ADDRESS
     Set server listen address.
+    (Config option: bind)
 
   --no-auto-h1
     By default, if a markdown document does not start with an H1 caption,
     it will be added automatically based on the file name. To disable this
     behavior, use --no-auto-h1.
+    (Config option: auto_h1)
 
   --no-syntax
     Disable code syntax highlighting.
+    (Config option: highlighter)
 
   --no-line-numbers
     Disable line numbering for syntax highlighter.
+    (Config option: line_numbers)
 
   --no-sidebar
     Disable sidebar navigation.
+    (Config option: sidebar)
 
   --no-auto-nav
     Disable automatic generation of footer navigation for folder README 
     files.
+    (Config option: auto_nav)
+
+  --theme FOLDER
+    Use a custom theme. FOLDER is either absolute or relative to the main
+    documentation path.
+    (Config option: theme)
 
   --index
     Build or rebuild the index for the search page.
+    (Config option: index)
 
   --toc FILE
     Generate a table of contents file. 
+    (Config option: toc)
 
   --and-quit
     Quit instead of running the server. Useful with --index or --toc.
@@ -49,4 +74,8 @@ Examples:
   madness --no-sidebar --no-auto-nav
   madness --index --and-quit
   madness --toc "Table of Contents.md" --index --and-quit
+  madness --theme _mytheme
+  madness create config
+  madness create theme
+
 

data/lib/madness/server_base.rb

@@ -6,15 +6,9 @@ module Madness
   class ServerBase < Sinatra::Application
     helpers ServerHelper
 
-    Sass::Plugin.options[:template_location] = 'app/styles'
-    Sass::Plugin.options[:css_location] = 'app/public/css'
     Slim::Engine.set_options pretty: true
-
     use Sass::Plugin::Rack
-
     set :root, File.expand_path('../../', __dir__)
-    set :views, File.expand_path('../../app/views', __dir__)
-    set :public_folder, File.expand_path('../../app/public', __dir__)
     set :server, :puma
 
     configure :development do
@@ -31,6 +25,17 @@ module Madness
       use Rack::TryStatic, root: "#{config.path}/", :urls => %w[/]
       set :bind, config.bind
       set :port, config.port
+
+      set_tempalate_locations
+    end
+
+    def self.set_tempalate_locations
+      theme = Theme.new config.theme
+      
+      set :views, theme.views_path
+      set :public_folder, theme.public_path
+      Sass::Plugin.options[:template_location] = theme.css_source_path
+      Sass::Plugin.options[:css_location] = theme.css_target_path
     end
 
     def self.config

data/lib/madness/settings.rb

@@ -8,8 +8,18 @@ module Madness
   class Settings
     include Singleton
 
-    attr_accessor :port, :bind, :path, :auto_h1, 
-      :highlighter, :line_numbers, :index, :toc, :sidebar, :auto_nav
+    attr_accessor \
+      :auto_h1, 
+      :auto_nav,
+      :bind, 
+      :highlighter, 
+      :index, 
+      :line_numbers, 
+      :path, 
+      :port, 
+      :sidebar, 
+      :theme,
+      :toc
 
     def initialize
       reset
@@ -43,6 +53,7 @@ module Madness
       self.highlighter = true
       self.line_numbers = true
       self.index = false
+      self.theme = nil
     end
 
     def load_from_file

data/lib/madness/templates/madness.yml

@@ -0,0 +1,14 @@
+# Madness configuration file
+# Uncomment any of the options below
+
+# path: '.'
+# port: '3000'
+# bind: '0.0.0.0'
+# sidebar: true
+# auto_h1: true
+# auto_nav: true
+# highlighter: true
+# line_numbers: true
+# index: false
+# toc: Table of Contents
+# theme: _theme

data/lib/madness/theme.rb

@@ -0,0 +1,30 @@
+module Madness
+  class Theme
+    attr_reader :path
+
+    def initialize(path=nil)
+      @path = path
+    end
+
+    def views_path
+      custom? ? "#{path}/views" : File.expand_path('../../app/views', __dir__)
+    end
+
+    def public_path
+      custom? ? "#{path}/public" : File.expand_path('../../app/public', __dir__)
+    end
+
+    def css_source_path
+      custom? ? "#{path}/styles" : 'app/styles'
+    end
+
+    def css_target_path
+      custom? ? "#{path}/public/css" : 'app/public/css'
+    end
+
+    def custom?
+      @custom ||= (path and Dir.exist? path)
+    end
+  end
+end
+

data/lib/madness/version.rb

@@ -1,3 +1,3 @@
 module Madness
-  VERSION = "0.5.5"
+  VERSION = "0.5.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: madness
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.5.6
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-26 00:00:00.000000000 Z
+date: 2018-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sass
@@ -381,6 +381,8 @@ files:
 - lib/madness/server_helper.rb
 - lib/madness/settings.rb
 - lib/madness/table_of_contents.rb
+- lib/madness/templates/madness.yml
+- lib/madness/theme.rb
 - lib/madness/version.rb
 homepage: https://github.com/DannyBen/madness
 licenses: