add reference section to documents

hal9ai · Jun 13, 2024 · 9e19a1d · 9e19a1d
1 parent 60fbfc0
commit 9e19a1d
Show file tree

Hide file tree

Showing 12 changed files with 159 additions and 122 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,21 +1,25 @@
 # Changelog
 
-## v2.2.4
+## 2.2.6
+
+- Add `hidden` parameter to `save` to save file as hidden
+
+## 2.2.4
 
 - Add helper function `extract` to extract code blocks
 
-## v2.2.3
+## 2.2.3
 
 - Only add extensions to `save` and `load` when needed
 
-## v2.2.0
+## 2.2.0
 
 - Add support for name parameter in deploy to overwrite content
 
-## v2.1.8
+## 2.1.8
 
 - Add support for `load`, `save` functions
 
-## v2.0.0
+## 2.0.0
 
 - Create and deploy projects
diff --git a/python/hal9/code.py b/python/hal9/code.py
@@ -1,7 +1,7 @@
 import re
 
-def extract(text, language):
+def extract(markdown, language):
     pattern = re.compile(rf'```{language}\s+(.*?)```', re.DOTALL)
-    code_blocks = pattern.findall(text)
+    code_blocks = pattern.findall(markdown)
     code = '\n'.join(code_blocks)
     return code
diff --git a/python/hal9/iobind.py b/python/hal9/iobind.py
@@ -8,20 +8,36 @@ def add_extension(path):
     path = path + ".json"
   return Path(path)
 
+def get_hidden(file_path):
+  hidden = f".${file_path}"
+  if hidden.exists():
+    return hidden
+  return file_path
+
+def add_hidden(file_path, hidden):
+  prefix = ""
+  if hidden:
+    prefix = "."
+  return prefix + file_path
+
 def get_extension(file_path):
   _, extension = os.path.splitext(file_path)
   return extension.lstrip('.')
 
-def load(file, default):
-  file_path = add_extension(file + ".json")
+def load(name, default):
+  file_path = add_extension(name)
+  file_path = get_hidden(file_path, hidden)
+
   if file_path.exists():
     contents = json.loads(file_path.read_text())
   else:
     contents = default
   return contents
 
-def save(name, contents):
+def save(name, contents, hidden = False):
   file_path = add_extension(name)
+  file_path = add_hidden(file_path, hidden)
+
   extension = get_extension(file_path)
   if (extension == "json"):
     contents = json.dumps(contents, indent=2)

diff --git a/python/pyproject.toml b/python/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "hal9"
-version = "2.2.5"
+version = "2.2.6"
 description = ""
 authors = ["Javier Luraschi <[email protected]>"]
 readme = "README.md"

diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -30,25 +30,31 @@ const config = {
         docs: {
           sidebarPath: './sidebars.js',
           editUrl:
-            'https://github.com/hal9ai/hal9/tree/main/docs/reference',
+            'https://github.com/hal9ai/hal9/tree/main/website/learn',
           path: 'learn',
           routeBasePath: 'learn',
         },
         blog: {
           showReadingTime: true,
           editUrl:
-            'https://github.com/hal9ai/hal9/tree/main/docs/blog',
+            'https://github.com/hal9ai/hal9/tree/main/website/blog',
         },
         theme: {
-          customCss: require.resolve('./src/css/custom.scss'),
+          customCss: require.resolve('./src/css/custom.css'),
         },
         googleAnalytics: {
           trackingID: 'UA-188412659-2',
         },
       }),
     ],
   ],
-
+  plugins: [
+    ['@docusaurus/plugin-content-docs', {
+      id: 'reference',
+      path: 'reference',
+      routeBasePath: 'reference',
+    }]
+  ],
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
@@ -69,6 +75,7 @@ const config = {
             position: 'left',
             label: 'Learn',
           },
+          {to: '/reference/code', label: 'Reference', position: 'left'},
           {to: '/blog', label: 'Blog', position: 'left'},
           {
             href: 'https://github.com/hal9ai/hal9',

diff --git a/website/learn/genapps/apps/chatbots.md b/website/learn/genapps/apps/chatbots.md
@@ -41,7 +41,7 @@ word = input("Give me a word: ")
 all_words.append(word)
 print(f"I remember: {', '.join(all_words)}")
 
-h9.save("words", messages)
+h9.save("words", messages, hidden = True)
 ```
 
 In contrast to stateless, a computer program that does not need to remember its state on its own, is referred to as **stateles**. The system as a whole, chatbot and file, is indeed stateful; however, giving someone else the job of remembering state (in this case the file) makes programs more reliable, efficient, and is a concept we will use through this guide.

diff --git a/website/learn/genapps/llmapps/code.md b/website/learn/genapps/llmapps/code.md
@@ -22,8 +22,7 @@ completion = OpenAI().chat.completions.create(
  )
 
 code = h9.extract(completion.choices[0].message.content)
-print(code)
-exec(code)
+print(exec(code))
 ```
 
 LLMs are not really that good at doing math; however, with the help of this code interpreter, we can run complex calculations that are impossible to run using only a LLM
@@ -57,7 +56,7 @@ completion = OpenAI().chat.completions.create(
  )
 
 code = h9.extract(completion.choices[0].message.content)
-exec(code)
+print(exec(code))
 ```
 
 ## Apps

diff --git a/website/learn/genapps/llmapps/intro.md b/website/learn/genapps/llmapps/intro.md
@@ -53,7 +53,7 @@ for chunk in stream:
     print(chunk.choices[0].delta.content, end="")
 
 messages.append({"role": "ai", "content": completion.choices[0].message.content})
-h9.save("messages", messages)
+h9.save("messages", messages, hidden = True)
 ```
 
 ## Groq
@@ -77,5 +77,5 @@ for chunk in completion:
   print(chunk.choices[0].delta.content or "", end="")
 
 messages.append({"role": "ai", "content": completion.choices[0].message.content})
-h9.save("messages", messages)
+h9.save("messages", messages, hidden = True)
 ```
diff --git a/website/reference/code.md b/website/reference/code.md
@@ -0,0 +1,12 @@
+# Code
+
+Convenience functions to process code.
+
+## Extract
+`extract(markdown, language)` <br/><br/>
+Extracts all `language` code blocks from `markdown` text
+
+| Param | Type | Description |
+| --- | --- | --- |
+| markdown | <code>String</code> | The markdown to extract blocks from. |
+| language | <code>String</code> | The language of the code blocks. |
diff --git a/website/reference/files.md b/website/reference/files.md
@@ -0,0 +1,26 @@
+# Files
+
+Convenience functions to load and save files.
+
+## Load
+
+`load (name, default)` <br/><br/>
+
+Returns the contents of `name` file, `default` if it does not exist.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| name | <code>String</code> | The file name of the file to load. |
+| default | <code>Object</code> | The default object when file does not exists. |
+
+## Save
+
+`save (name, contents, hidden)` <br/><br/>
+
+Saves to `name` file the given `contents`.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| name | <code>String</code> | The file name of the file to save. |
+| contents | <code>String</code> | The contents of the file to save. |
+| hidden | <code>Boolean</code> | `True` to make file visible user, defaults to `False`.
diff --git a/website/src/css/custom.css b/website/src/css/custom.css
@@ -0,0 +1,74 @@
+/** * Any CSS included here will be global. The classic template * bundles Infima by default. Infima is a CSS framework designed to * work well for content-centric websites. */
+
+/* You can override the default Infima variables here. */
+
+:root {
+   --ifm-color-primary: #2e8555;
+   --ifm-color-primary-dark: #29784c;
+   --ifm-color-primary-darker: #277148;
+   --ifm-color-primary-darkest: #205d3b;
+   --ifm-color-primary-light: #33925d;
+   --ifm-color-primary-lighter: #359962;
+   --ifm-color-primary-lightest: #3cad6e;
+   --ifm-code-font-size: 95%;
+   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+nav .github-link:before {
+  content: '';
+  width: 24px;
+  height: 24px;
+  display: flex;
+}
+
+nav .github-link:hover {
+  opacity: 0.6;
+}
+
+html[data-theme=light] nav .github-link:before {
+  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") no-repeat;
+}
+
+html[data-theme=dark] nav .github-link:before {
+  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") no-repeat;
+}
+
+.footer.footer--dark {
+  background: #242526;
+}
+
+p {
+  text-align: justify;
+}
+
+.floating {
+  borderRadius: 2px;
+  padding: 0.2rem;
+  width: 20%;
+  margin: 2%;
+  minWidth: 180px;
+  display: inline-block;
+  verticalAlign: top;
+}
+
+@media (max-width: 1250px) {
+  .floating {
+    width: 100%;
+  }
+}
+
+.FloatingWrapper {
+  display: flex;
+  margin-bottom: 20px;
+}
+
+.FloatingWrapper a:link, .FloatingWrapper a:visited, .FloatingWrapper a:hover, .FloatingWrapper a:active {
+  text-decoration: none;
+}
+
+@media (max-width: 1024px) {
+  .FloatingWrapper {
+    display: inline-block;
+  }
+}
+
diff --git a/website/src/css/custom.scss b/website/src/css/custom.scss