diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/404.html b/404.html new file mode 100644 index 0000000..a7b5091 --- /dev/null +++ b/404.html @@ -0,0 +1,33 @@ + + +
+ + + + + +Moduler is a standard for putting documentation just in your Python code. It is proposed to provide another option other than the current standard of putting documentation in a separate file. Though it is not new to mix documentation with code, in Moduler, you can also do
We believe in this way we can provide much more context information to new contributors who are not familiar with the codebase. It is also important for AI-based agents to understand the codebase and develop it.
Putting sections in Moduler is as easy as putting sections in Markdown. You just need to put a #
before your section title in a comment environment starting with """
. For example,
"""
+# Section 1
+The following is a function.
+"""
+
+
+def foo():
+ pass
+
+
+"""
+# Section 2
+The following is another function.
+"""
+
+
+def bar():
+ pass
+
In this way, foo()
and bar()
will have sections Section 1
and Section 2
respectively. The sections will also contain the comments under them.
Your section can also contain classes add levels. For example,
"""
+# Top Section
+## Section 1
+"""
+
+
+class Foo:
+ """
+ # Section 1
+ The following is a function.
+ """
+
+ def foo(self):
+ pass
+
+ """
+ # Section 2
+ The following is another function.
+ """
+
+ def bar(self):
+ pass
+
+
+"""
+## Section 2
+"""
+
+
+def baz():
+ pass
+
You add .tree.yml
file in a folder to add sections in it. For example, in the following folder
a_folder
+- __init__.py
+- a.py
+- b.py
+- c.py
+- .tree.yml
+
You can put a
,b
in a section by putting
sections:
+ your section title:
+ - a
+ - b
+default section: you default section title
+
Then a
and b
will be in the section your section title
and c
will be in the section you default section title
.
You can also add examples to your functions and classes. Just use the @example
decorator. For example,
from moduler.decorator import example
+
+
+@example
+def how_to_use_foo():
+ """
+ # Example
+ The following is an example of using \`foo()\`.
+ """
+ foo()
+
In a similar way, you can also mark todos in your code. Just use the @todo
decorator. For example,
from moduler.decorator import todo
+
+
+@todo
+def todo_foo():
+ """
+ # Todo
+ The following is a todo.
+ """
+ foo()
+
+
+@todo("This function is buggy. Fix it.")
+def buggy_foo():
+ foo(a=b)
+
Moduler is a standard for putting documentation just in your Python code. It is proposed to provide another option other than the current standard of putting documentation in a separate file. Though it is not new to mix documentation with code, in Moduler, you can also do
We believe in this way we can provide much more context information to new contributors who are not familiar with the codebase. It is also important for AI-based agents to understand the codebase and develop it.
Putting sections in Moduler is as easy as putting sections in Markdown. You just need to put a #
before your section title in a comment environment starting with """
. For example,
"""
+# Section 1
+The following is a function.
+"""
+
+
+def foo():
+ pass
+
+
+"""
+# Section 2
+The following is another function.
+"""
+
+
+def bar():
+ pass
+
In this way, foo()
and bar()
will have sections Section 1
and Section 2
respectively. The sections will also contain the comments under them.
Your section can also contain classes add levels. For example,
"""
+# Top Section
+## Section 1
+"""
+
+
+class Foo:
+ """
+ # Section 1
+ The following is a function.
+ """
+
+ def foo(self):
+ pass
+
+ """
+ # Section 2
+ The following is another function.
+ """
+
+ def bar(self):
+ pass
+
+
+"""
+## Section 2
+"""
+
+
+def baz():
+ pass
+
You add .tree.yml
file in a folder to add sections in it. For example, in the following folder
a_folder
+- __init__.py
+- a.py
+- b.py
+- c.py
+- .tree.yml
+
You can put a
,b
in a section by putting
sections:
+ your section title:
+ - a
+ - b
+default section: you default section title
+
Then a
and b
will be in the section your section title
and c
will be in the section you default section title
.
You can also add examples to your functions and classes. Just use the @example
decorator. For example,
from moduler.decorator import example
+
+
+@example
+def how_to_use_foo():
+ """
+ # Example
+ The following is an example of using `foo()`.
+ """
+ foo()
+
In a similar way, you can also mark todos in your code. Just use the @todo
decorator. For example,
from moduler.decorator import todo
+
+
+@todo
+def todo_foo():
+ """
+ # Todo
+ The following is a todo.
+ """
+ foo()
+
+
+@todo("This function is buggy. Fix it.")
+def buggy_foo():
+ foo(a=b)
+
Moduler can be regarded as an effort toward the idea - literate programming. We think literate programming gets even more important in the era of AI for it provides more context information for AI-based agents to understand the codebase.
All the programming languages encourage the programmers to put their code in the tree structure. For example, you can put your functions in difference classes, in different files and put the files in different folders. However, it is still very common to put a lot of functions in a single file, in which the codes are arranged in an almost flat structure.
Moduler helps this by adding a zero-cost way to add sections to your functions and classes. It makes another step towards a more tree-like structure of the codebase. We believe this will help the programmers to understand the codebase better. See Method of Loci for more details.
EvoNote is using Moduler to document its codebase. You can have a good visualization of EvoNote's codebase by running EvoNote visualization.