change #' to # and require ## for regular julia comments, fix #3

docs/src/customprocessing.md

@@ -27,8 +27,8 @@ We could of course update our source file before generating the docs, but we cou
 instead use a `preprocess` function that splices the date into the source for us.
 Consider the following source file:
 ```julia
-#' # Example
-#' This example was generated DATEOFTODAY
+# # Example
+# This example was generated DATEOFTODAY
 
 x = 1 // 3
 ```

docs/src/fileformat.md

@@ -8,25 +8,27 @@ stay up do date with other changes in your package.
 ## [**2.1.** Syntax](@id Syntax)
 
 The basic syntax is simple:
-- lines starting with `#'` is treated as markdown,
+- lines starting with `# ` are treated as markdown,
 - all other lines are treated as julia code.
 
-The reason for using `#'` instead of `#` is that we want to be able to use `#` as comments,
-just as in a regular script. Lets look at a simple example:
+!!! note
+    If you want regular julia comments in the source file use `## ` instead of `# `.
+
+Lets look at a simple example:
 ```julia
-#' # Rational numbers
-#'
-#' In julia rational numbers can be constructed with the `//` operator.
-#' Lets define two rational numbers, `x` and `y`:
+# # Rational numbers
+#
+# In julia rational numbers can be constructed with the `//` operator.
+# Lets define two rational numbers, `x` and `y`:
 
 x = 1//3
 y = 2//5
 
-#' When adding `x` and `y` together we obtain a new rational number:
+# When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
 ```
-In the lines `#'` we can use regular markdown syntax, for example the `#`
+In the lines starting with `#` we can use regular markdown syntax, for example the `#`
 used for the heading and the backticks for formatting code. The other lines are regular
 julia code. We note a couple of things:
 - The script is valid julia, which means that we can `include` it and the example will run
@@ -60,11 +62,11 @@ using Documenter. Obviously we don't want to include this in the notebook,
 since `@docs` is Documenter syntax that the notebook will not understand. This
 is a case where we can prepend `#md` to those lines:
 ````julia
-#md #' ```@docs
-#md #' Literate.markdown
-#md #' Literate.notebook
-#md #' Literate.markdown
-#md #' ```
+#md # ```@docs
+#md # Literate.markdown
+#md # Literate.notebook
+#md # Literate.markdown
+#md # ```
 ````
 The lines in the example above would be filtered out in the preprocessing step, unless we are
 generating a markdown file. When generating a markdown file we would simple remove

docs/src/outputformats.md

@@ -4,16 +4,16 @@ When the source is parsed, and have been processed it is time to render the outp
 We will consider the following source snippet:
 
 ```julia
-#' # Rational numbers
-#'
-#' In julia rational numbers can be constructed with the `//` operator.
-#' Lets define two rational numbers, `x` and `y`:
+# # Rational numbers
+#
+# In julia rational numbers can be constructed with the `//` operator.
+# Lets define two rational numbers, `x` and `y`:
 
 x = 1//3
 #-
 y = 2//5
 
-#' When adding `x` and `y` together we obtain a new rational number:
+# When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
 ```
@@ -45,7 +45,7 @@ z = x + y
 ```
 ````
 
-We note that lines starting with `#'` is printed as regular markdown,
+We note that lines starting with `# ` are printed as regular markdown,
 and the code lines have been wrapped in `@example` blocks.
 
 Some of the output rendering can be controlled with keyword arguments to
@@ -77,8 +77,8 @@ In[3]:  │ z = x + y
 Out[3]: │ 11/15
 ```
 
-We note that lines starting with `#'` is put in markdown cells,
-and the code lines have been put in code cells. By default the notebook
+We note that lines starting with `# ` are placed in markdown cells,
+and the code lines have been placed in code cells. By default the notebook
 is also executed and output cells populated. The current working directory
 is set to the specified output directory the notebook is executed.
 Some of the output rendering can be controlled with keyword
@@ -101,7 +101,7 @@ y = 2//5
 z = x + y
 ```
 
-We note that lines starting with `#'` are removed and only the
+We note that lines starting with `# ` are removed and only the
 code lines have been kept. Some of the output rendering can be controlled
 with keyword arguments to [`Literate.script`](@ref):
 

docs/src/pipeline.md

@@ -30,38 +30,38 @@ and mark them as either markdown or code according to the rules described in the
 [Syntax](@ref Syntax) section. Lets consider the example from the previous section
 with each line categorized:
 ```
-#' # Rational numbers                                                     <- markdown
-#'                                                                        <- markdown
-#' In julia rational numbers can be constructed with the `//` operator.   <- markdown
-#' Lets define two rational numbers, `x` and `y`:                         <- markdown
-                                                                          <- code
-x = 1 // 3                                                                <- code
-y = 2 // 5                                                                <- code
-                                                                          <- code
-#' When adding `x` and `y` together we obtain a new rational number:      <- markdown
-                                                                          <- code
-z = x + y                                                                 <- code
+# # Rational numbers                                                     <- markdown
+#                                                                        <- markdown
+# In julia rational numbers can be constructed with the `//` operator.   <- markdown
+# Lets define two rational numbers, `x` and `y`:                         <- markdown
+                                                                         <- code
+x = 1 // 3                                                               <- code
+y = 2 // 5                                                               <- code
+                                                                         <- code
+# When adding `x` and `y` together we obtain a new rational number:      <- markdown
+                                                                         <- code
+z = x + y                                                                <- code
 ```
 
 In the next step the lines are grouped into "chunks" of markdown and code.
 This is done by simply collecting adjacent lines of the same "type" into
 chunks:
 ```
-#' # Rational numbers                                                     ┐
-#'                                                                        │
-#' In julia rational numbers can be constructed with the `//` operator.   │ markdown
-#' Lets define two rational numbers, `x` and `y`:                         ┘
-                                                                          ┐
-x = 1 // 3                                                                │
-y = 2 // 5                                                                │ code
-                                                                          ┘
-#' When adding `x` and `y` together we obtain a new rational number:      ] markdown
-                                                                          ┐
-z = x + y                                                                 ┘ code
+# # Rational numbers                                                     ┐
+#                                                                        │
+# In julia rational numbers can be constructed with the `//` operator.   │ markdown
+# Lets define two rational numbers, `x` and `y`:                         ┘
+                                                                         ┐
+x = 1 // 3                                                               │
+y = 2 // 5                                                               │ code
+                                                                         ┘
+# When adding `x` and `y` together we obtain a new rational number:      ] markdown
+                                                                         ┐
+z = x + y                                                                ┘ code
 ```
 
 In the last parsing step all empty leading and trailing lines for each chunk
-are removed, but empty lines *within the same* block are kept. The leading `#' `
+are removed, but empty lines *within the same* block are kept. The leading `# `
 tokens are also removed from the markdown chunks. Finally we would
 end up with the following 4 chunks:
 
@@ -112,7 +112,7 @@ The example above would result in two consecutive code-chunks.
 After the parsing it is time to generate the output. What is done in this step is
 very different depending on the output target, and it is describe in more detail in
 the Output format sections: [Markdown Output](@ref), [Notebook Output](@ref) and
-[Script Output](@ref). In short, the following is happening:
+[Script Output](@ref). Using the default settings, the following is happening:
 
 * Markdown output: markdown chunks are printed as-is, code chunks are put inside
   a code fence (defaults to `@example`-blocks),

examples/example.jl

@@ -1,56 +1,56 @@
-#' # **7.** Example
-#'
-#' This is an example generated with Literate based on this
-#' source file: [`example.jl`](@__REPO_ROOT_URL__examples/example.jl).
-#' You are seeing the
-#md #' html-output which Documenter have generated based on a markdown
-#md #' file generated with Literate. The corresponding notebook
-#md #' can be found here: [`example.ipynb`](@__NBVIEWER_ROOT_URL__generated/example.ipynb),
-#nb #' generated notebook output. The corresponding markdown (html) output
-#nb #' can be found here: [`example.html`](https://fredrikekre.github.io/Literate.jl/latest/generated/example.html),
-#' and the plain script output can be found here: [`example.jl`](./example.jl).
+# # **7.** Example
+#
+# This is an example generated with Literate based on this
+# source file: [`example.jl`](@__REPO_ROOT_URL__examples/example.jl).
+# You are seeing the
+#md # html-output which Documenter have generated based on a markdown
+#md # file generated with Literate. The corresponding notebook
+#md # can be found here: [`example.ipynb`](@__NBVIEWER_ROOT_URL__generated/example.ipynb),
+#nb # generated notebook output. The corresponding markdown (html) output
+#nb # can be found here: [`example.html`](https://fredrikekre.github.io/Literate.jl/latest/generated/example.html),
+# and the plain script output can be found here: [`example.jl`](./example.jl).
 
-#' It is recommended to have the [source file](@__REPO_ROOT_URL__examples/example.jl)
-#' available when reading this, to better understand how the syntax in the source file
-#' corresponds to the output you are seeing.
+# It is recommended to have the [source file](@__REPO_ROOT_URL__examples/example.jl)
+# available when reading this, to better understand how the syntax in the source file
+# corresponds to the output you are seeing.
 
-#' ### Basic syntax
-#' The basic syntax for Literate is simple, lines starting with `#'` is interpreted
-#' as markdown, and all the other lines are interpreted as code. Here is some code:
+# ### Basic syntax
+# The basic syntax for Literate is simple, lines starting with `# ` is interpreted
+# as markdown, and all the other lines are interpreted as code. Here is some code:
 
 x = 1//3
 y = 2//5
 
-#' In markdown sections we can use markdown syntax. For example, we can
-#' write *text in italic font*, **text in bold font** and use
-#' [links](https://www.youtube.com/watch?v=dQw4w9WgXcQ).
+# In markdown sections we can use markdown syntax. For example, we can
+# write *text in italic font*, **text in bold font** and use
+# [links](https://www.youtube.com/watch?v=dQw4w9WgXcQ).
 
-#' It is possible to filter out lines depending on the output using the
-#' `#md`, `#nb`, `#jl` and `#src` tags (see [Filtering Lines](@ref)):
-#md #' - This line starts with `#md` and is thus only visible in the markdown output.
-#nb #' - This line starts with `#nb` and is thus only visible in the notebook output.
-#jl #' - This line starts with `#jl` and is thus only visible in the notebook output.
-#src #' - This line starts with `#src` and is thus only visible in the source file.
+# It is possible to filter out lines depending on the output using the
+# `#md`, `#nb`, `#jl` and `#src` tags (see [Filtering Lines](@ref)):
+#md # - This line starts with `#md` and is thus only visible in the markdown output.
+#nb # - This line starts with `#nb` and is thus only visible in the notebook output.
+#jl # - This line starts with `#jl` and is thus only visible in the notebook output.
+#src # - This line starts with `#src` and is thus only visible in the source file.
 
-#' The source file is parsed in chunks of markdown and code. Starting a line
-#' with `#-` manually inserts a chunk break. For example, if we want to
-#' display the output of the following operations we may insert `#-` in
-#' between. These two code blocks will now end up in different
-#' `@example`-blocks in the markdown output, and two different notebook cells
-#' in the notebook output.
+# The source file is parsed in chunks of markdown and code. Starting a line
+# with `#-` manually inserts a chunk break. For example, if we want to
+# display the output of the following operations we may insert `#-` in
+# between. These two code blocks will now end up in different
+# `@example`-blocks in the markdown output, and two different notebook cells
+# in the notebook output.
 
 x + y
 
 #-
 
 x * y
 
-#' ### Output Capturing
-#' Code chunks are by default placed in Documenter `@example` blocks in the generated
-#' markdown. This means that the output will be captured in a block when Documenter is
-#' building the docs. In notebooks the output is captured in output cells, if the
-#' `execute` keyword argument is set to true. Output to `stdout`/`stderr` is also
-#' captured.
+# ### Output Capturing
+# Code chunks are by default placed in Documenter `@example` blocks in the generated
+# markdown. This means that the output will be captured in a block when Documenter is
+# building the docs. In notebooks the output is captured in output cells, if the
+# `execute` keyword argument is set to true. Output to `stdout`/`stderr` is also
+# captured.
 
 function foo()
     println("This string is printed to stdout.")
@@ -59,26 +59,26 @@ end
 
 foo()
 
-#' ### Custom processing
-#'
-#' It is possible to give Literate custom pre- and post-processing functions.
-#' For example, here we insert two placeholders, which we will replace with
-#' something else at time of generation. We have here replaced our placeholders
-#' with `z` and `1.0 + 2.0im`:
+# ### Custom processing
+#
+# It is possible to give Literate custom pre- and post-processing functions.
+# For example, here we insert two placeholders, which we will replace with
+# something else at time of generation. We have here replaced our placeholders
+# with `z` and `1.0 + 2.0im`:
 
 MYVARIABLE = MYVALUE
 
-#' ### [Documenter.jl interaction](@id documenter-interaction)
-#'
-#' In the source file it is possible to use Documenter.jl style references,
-#' such as `@ref` and `@id`. These will be filtered out in the notebook output.
-#' For example, [here is a link](@ref documenter-interaction), but it is only
-#' visible as a link if you are reading the markdown output. We can also
-#' use equations:
-#'
-#' ```math
-#' \int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega
-#' ```
-#'
-#' using Documenters math syntax. Documenters syntax is automatically changed to
-#' `\begin{equation} ... \end{equation}` in the notebook output to display correctly.
+# ### [Documenter.jl interaction](@id documenter-interaction)
+#
+# In the source file it is possible to use Documenter.jl style references,
+# such as `@ref` and `@id`. These will be filtered out in the notebook output.
+# For example, [here is a link](@ref documenter-interaction), but it is only
+# visible as a link if you are reading the markdown output. We can also
+# use equations:
+#
+# ```math
+# \int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega
+# ```
+#
+# using Documenters math syntax. Documenters syntax is automatically changed to
+# `\begin{equation} ... \end{equation}` in the notebook output to display correctly.