[lxc-devel] [linuxcontainers.org/master] Added content to Readme.md and Contributing.md
toby63 on Github
lxc-bot at linuxcontainers.org
Sun Nov 22 23:00:58 UTC 2020
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 381 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20201122/747c9cf4/attachment.bin>
-------------- next part --------------
From db9f88ace34bf82eb191f00f5701d9ad6e261625 Mon Sep 17 00:00:00 2001
From: Tobias Gerold <tobias at g3ro.eu>
Date: Sat, 21 Nov 2020 20:38:33 +0100
Subject: [PATCH 1/3] README.md - fixed markdown version
Signed-off-by: Tobias Gerold <tobias at g3ro.eu>
---
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 3f47d76..8ca199b 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ part is located at https://github.com/lxc/lxd-demo-server
* python3 (>= 3.3)
* python3-bs4
* python3-jinja2
- * python3-markdown (<3.0.0)
+ * python3-markdown
* python3-pygments
## Generating the website
From 65741c64055edc3eefb87b98560c2ca07a3a2916 Mon Sep 17 00:00:00 2001
From: Tobias Gerold <tobias at g3ro.eu>
Date: Sun, 22 Nov 2020 22:31:42 +0100
Subject: [PATCH 2/3] README.md - restructured + mentioned translations and
content requests
Signed-off-by: Tobias Gerold <tobias at g3ro.eu>
---
README.md | 64 +++++++++++++++++++++++++++++++++++++++++++------------
1 file changed, 50 insertions(+), 14 deletions(-)
diff --git a/README.md b/README.md
index 8ca199b..b11aab1 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,26 @@ This branch contains the content and site generator of the
https://linuxcontainers.org website. Backend code for [Try it](https://linuxcontainers.org/lxd/try-it/)
part is located at https://github.com/lxc/lxd-demo-server
-## Dependencies
+## Contributing
+
+Fixes, new content and translations are greatly appreciated.
+Read our [contributing guidelines](CONTRIBUTING.md) for details.
+
+### Open Issues
+
+Take a look at the [open issues on Github](https://github.com/lxc/linuxcontainers.org/issues/), to see where you could help.
+
+For example:
+
+* [Advanced Guide for LXD](https://github.com/lxc/linuxcontainers.org/issues/413)
+
+## Generate & run a local copy
+
+To generate & run a local copy of the website, follow the instructions below.
+
+### Dependencies
+
+Install the following software (naming may depends on your distribution):
* man2html-base
* python3 (>= 3.3)
@@ -13,32 +32,49 @@ part is located at https://github.com/lxc/lxd-demo-server
* python3-markdown
* python3-pygments
-## Generating the website
+### Clone the repo
+
+ git clone https://github.com/lxc/linuxcontainers.org
+
+### Generating the website
./generate
-## Launching website within container
+### Launching the website
-Make sure that the container has access to the website folder that you just cloned.
+After generating the website(above), run these commands(Ubuntu-specific):
-You can use a bind-mount for the folder if necessary (host => container OR container => host)
+ cd output
+ python3 -m http.server 8777
+
+Now you can access the website in your browser by using your local IP address and port:
+
+ 127.0.0.1:8777
+
+#### (Alternative) Launching within a container
+
+**Inside the container:**
+
+Install the dependencies, clone the repo and generate the website (same as above).
-After generating the website(above), run these commands(Ubuntu-specific) within the container:
+After generating the website, run these commands(Ubuntu-specific):
cd output
python3 -m http.server 8777
-You now need to obtain the IP address for the specific container. You can now navigate to the site (from the host) with the following example IP address:
+**On the host:**
+
+You can now navigate to the site (in a browser of your choice) with the container's IP address, for example:
+
+ 185.5.3.12:8777
+
+## Bug reports & Content requests
+
+Bug reports, requests and ideas regarding the website can be filed at https://github.com/lxc/linuxcontainers.org/issues/new
+
-> 185.5.3.12:8777
-## Bug reports
-Bug reports can be filed at https://github.com/lxc/linuxcontainers.org/issues/new
-## Contributing
-Fixes and new content are greatly appreciated but please read our
-[contributing guidelines](CONTRIBUTING.md) first.
-Contributions to this project should be sent as pull requests on GitHub.
From 06fba862691d55589e5d4e2565c293fc52cb7bb2 Mon Sep 17 00:00:00 2001
From: Tobias Gerold <tobias at g3ro.eu>
Date: Sun, 22 Nov 2020 22:33:41 +0100
Subject: [PATCH 3/3] CONTRIBUTING.md - added notes about commits, style &
content, translations and testing
Signed-off-by: Tobias Gerold <tobias at g3ro.eu>
---
CONTRIBUTING.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 100 insertions(+), 2 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e2bdecd..50e3d22 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -76,5 +76,103 @@ An example of a valid sign-off line is:
Use your real name and a valid e-mail address.
Sorry, no pseudonyms or anonymous contributions are allowed.
-We also require each commit be individually signed-off by their author,
-even when part of a larger set.
+**Note:**
+* Sign-off each commit individually, even when it is part of a larger set.
+* If multiple authors are participating, sign-off each commit individually by their author.
+
+# Commits
+
+* Prefer smaller commits over large commits: For example one for each section
+* Add useful messages to your commits, that describe the content or changes
+
+# Style & Content
+
+## Text- & Programming-Languages used
+
+* **Markdown:**
+ Standard Markdown language and the following extensions:
+
+ ```
+ codehilite
+ toc
+ extra
+ tables
+ footnotes
+ admonition
+ wikilinks
+ attr_list
+ fenced_code
+ ```
+
+ See also:
+
+ * [source file of generate](https://github.com/lxc/linuxcontainers.org/blob/master/generate) for currently enabled extensions.
+ * [python-markdown documentation](https://python-markdown.github.io/extensions/) for details.
+
+* **HTML:** Used only when necessary.
+
+### Special css-classes in use
+
+* For `Notes` and `Warnings`:
+
+ Add the css-class `.p-noteadm` directly below the content:
+
+ ```
+ !!! note "Note:"
+ Content
+ {: .p-noteadm }
+ ```
+
+
+## Guidelines for the content
+
+* create a Table of Content (TOC) manually (with a markdown list), the toc extension is only used for creation of hyperlinks.
+
+* write short and continuous text
+* use lists, tables & code tags
+* use headers for each section and sub-section
+
+## Translations
+
+Copy the original file you want to translate (if a file for the translation is not already existing) and rename it.
+
+**File name:**
+
+Add the shortcut of the language to the filename.
+For example, for the `advanced-guide.md`:
+
+ advanced-guide.ja.md # japanese version
+
+**Layout**:
+
+Keep the original layout.
+
+**Accuracy:**
+
+Translate as accurate as possible.
+
+**Quality:**
+
+You should have good language skills.
+
+**Completeness:**
+
+Your pull request does not have to be complete, every piece of translation is a good start.
+
+**Keep the original content:**
+
+Add the original text as comments inside the text, with:
+
+`<!-- original text -->`
+
+**Example:**
+
+Take a look at the [source file of the japanese version of the advanced guide](https://raw.githubusercontent.com/lxc/linuxcontainers.org/master/content/lxd/advanced-guide.ja.md).
+
+# Test your changes
+
+Before opening a pull request, you should test the changes you made.
+
+Generate and run a local copy of the website (see [Readme.md](README.md)) and check whether it works and looks correctly in your browser.
+
+
More information about the lxc-devel
mailing list