web/style: Add a comment in the generated css file for the doc in the main repo
[ffmpeg-web.git] / README
diff --git a/README b/README
index 130f081..2276820 100644 (file)
--- a/README
+++ b/README
@@ -1,4 +1,68 @@
-This generates the ffmpeg.org website by fitting the navigation links onto
-source files and dropping the result in the htdocs/ directory.
+ffmpeg.org official website
 
-'make' generates the website, 'make clean' removes all generated files.
+
+GENERATE THE WEBSITE
+--------------------
+
+`lessc` is required to generate CSS of the website.[1]
+
+Type `make` to generate the website.
+Type `make clean` to remove the generated files.
+
+
+GENERATE THE DOCUMENTATION
+--------------------------
+
+/!\ None of the generated versions of the website contain the documentation.
+
+To generate the documentation pages:
+- Add the HTML wrappers to your environment:
+  $ export FFMPEG_HEADER1="$(cat src/template_head1 src/template_doctitle src/template_head_prod)"
+  $ export FFMPEG_HEADER2="$(cat src/template_head2 src/template_doctitle src/template_head3)"
+  $ export FFMPEG_FOOTER="$(cat src/template_footer1 src/template_footer_prod src/template_footer2)"
+- Get the main ffmpeg repo:
+  $ git clone git://source.ffmpeg.org/ffmpeg.git
+- Compile the documentation using the ffmpeg main repo Makefile:
+  $ make doc
+- Copy the generated HTML files inside the website:
+  $ cp /path/to/ffmpeg/doc/*.html /path/to/ffmpeg-web/htdocs/
+
+In case of a major CSS update, please also update the `style.min.css` file in
+the main FFmpeg repo:
+  $ cat /path/to/ffmpeg-web/src/css_credit /path/to/ffmpeg-web/htdocs/css/{bootstrap.min.css,style.min.css} > /path/to/ffmpeg/doc/style.min.css
+
+
+WEBSITE DEVELOPERS INSTRUCTIONS
+-------------------------------
+
+npm, lessc and bower are required to generate the website in development.[2]
+
+Type `make DEV=1` to generate the website for development.
+Type `make clean DEV=1` to remove the generated files.
+
+In development mode, the external dependencies are downloaded through bower.
+
+Thanks to lessc, you can edit the *.less sources and see the changes on your
+browser without having to reload it.
+
+
+-----
+
+[1] lessc is available on the packages of some distributions.
+Otherwise, follow the instructions in [2].
+lessc depends on lots of stuff including npm, so if you wish to use a lighter version,
+you might want to check out the C++ version: http://www.vanderkroef.net/clessc.html
+
+[2] Install instructions, 2 methods:
+
+- Install everything globally (root required)
+  - Install npm from the packages or the sources: http://nodejs.org/
+  - Install lessc and bower using npm:
+    $ sudo npm install -g bower less
+
+- Install only npm globally
+  - Install npm from the packages or the sources: http://nodejs.org/
+  - Install lessc and bower in the current directory using npm:
+    $ npm install bower less
+  - Add the path to your environment:
+    $ export PATH=`pwd`/node_modules/bower/bin:`pwd`/node_modules/less/bin:$PATH