Clean up structure and remove stale code (#25)

* WIP: clean up structure and remove stale code

* additional cleanup

Author: alan707

config.yaml

@@ -14,103 +14,104 @@ hugo:
   languageCode: "en-us"
   theme: "docsy"
 
-# Content mapping - organized into 4 main categories
 content_mapping:
-  # TUTORIALS - Step-by-step guides for users
+  # set 'enable_category_indices' to true to generate _index.md files for categories
+  # also necessary to enable category menus in Sidebar
+  # When set to false it shows a monolithic list of all pages
+  # under the 'docs' menu item
+  enable_category_indices: false
   tutorials:
-    type: "tutorials"
-    weight: 10
-    category: "Tutorials"
+    type: "docs"
+    weight: 1
+    category: "tutorials"
   start:
-    type: "tutorials"
-    weight: 20
-    category: "Tutorials"
+    type: "docs"
+    weight: 2
+    category: "tutorials"
   basics:
-    type: "tutorials"
-    weight: 30
-    category: "Tutorials"
-    
-  # HOW-TO GUIDES - Practical instructions for specific tasks
+    type: "docs"
+    weight: 3
+    category: "tutorials"
   install:
-    type: "how-to-guides"
-    weight: 10
-    category: "How-To Guides"
+    type: "docs"
+    weight: 1
+    category: "how-to-guides"
   configure:
-    type: "how-to-guides"
-    weight: 20
-    category: "How-To Guides"
+    type: "docs"
+    weight: 2
+    category: "how-to-guides"
   build:
-    type: "how-to-guides"
-    weight: 30
-    category: "How-To Guides"
+    type: "docs"
+    weight: 3
+    category: "how-to-guides"
   run:
-    type: "how-to-guides"
-    weight: 40
-    category: "How-To Guides"
+    type: "docs"
+    weight: 4
+    category: "how-to-guides"
   remote:
-    type: "how-to-guides"
-    weight: 50
-    category: "How-To Guides"
+    type: "docs"
+    weight: 5
+    category: "how-to-guides"
   migrate:
-    type: "how-to-guides"
-    weight: 60
-    category: "How-To Guides"
+    type: "docs"
+    weight: 6
+    category: "how-to-guides"
   rules:
-    type: "how-to-guides"
-    weight: 70
-    category: "How-To Guides"
+    type: "docs"
+    weight: 7
+    category: "how-to-guides"
   docs:
-    type: "how-to-guides"
-    weight: 80
-    category: "How-To Guides"
-  
-  # EXPLANATIONS - In-depth articles explaining concepts and features
+    type: "docs"
+    weight: 8
+    category: "how-to-guides"
+  brand:
+    type: "docs"
+    weight: 9
+    category: "how-to-guides"
   concepts:
-    type: "explanations"
-    weight: 10
-    category: "Explanations"
+    type: "docs"
+    weight: 1
+    category: "explanations"
   extending:
-    type: "explanations"
-    weight: 20
-    category: "Explanations"
+    type: "docs"
+    weight: 2
+    category: "explanations"
   external:
-    type: "explanations"
-    weight: 30
-    category: "Explanations"
+    type: "docs"
+    weight: 3
+    category: "explanations"
   about:
-    type: "explanations"
-    weight: 40
-    category: "Explanations"
+    type: "docs"
+    weight: 4
+    category: "explanations"
   community:
-    type: "explanations"
-    weight: 50
-    category: "Explanations"
+    type: "docs"
+    weight: 5
+    category: "explanations"
   contribute:
-    type: "explanations"
-    weight: 60
-    category: "Explanations"
+    type: "docs"
+    weight: 6
+    category: "explanations"
   release:
-    type: "explanations"
-    weight: 70
-    category: "Explanations"
-  
-  # REFERENCE - Detailed reference material for advanced users
+    type: "docs"
+    weight: 7
+    category: "explanations"
   reference:
-    type: "reference"
-    weight: 10
-    category: "Reference"
+    type: "docs"
+    weight: 1
+    category: "reference"
   query:
-    type: "reference"
-    weight: 20
-    category: "Reference"
+    type: "docs"
+    weight: 2
+    category: "reference"
   versions:
-    type: "reference"
-    weight: 30
-    category: "Reference"
+    type: "docs"
+    weight: 3
+    category: "reference"
   advanced:
-    type: "reference"
-    weight: 40
-    category: "Reference"
+    type: "docs"
+    weight: 4
+    category: "reference"
 
 # CSS conversion settings
 css_conversion:

devsite_to_hugo_converter.py

@@ -86,8 +86,7 @@ def convert_documentation(self,
                 return False
 
             # Convert content files
-            conversion_stats = self._convert_content_files(
-                devsite_structure, source_path, output_path, dry_run,
+            conversion_stats = self._convert_content_files(source_path, output_path, dry_run,
                 incremental)
 
             # Convert static assets
@@ -140,8 +139,10 @@ def _create_output_structure(self, output_path: str) -> None:
             dir_path.mkdir(parents=True, exist_ok=True)
             logger.debug(f"Created directory: {dir_path}")
 
-    def _convert_content_files(self, devsite_structure: Dict, source_path: str,
-                               output_path: str, dry_run: bool,
+    def _convert_content_files(self, 
+                               source_path: str,
+                               output_path: str, 
+                               dry_run: bool,
                                incremental: bool) -> Dict:
         """Convert all content files from Devsite to Hugo format"""
         conversion_stats = {
@@ -172,9 +173,10 @@ def _convert_content_files(self, devsite_structure: Dict, source_path: str,
                 category_path = self._get_category_path(relative_path)
 
                 # Convert file
+                if category_path == Path("how-to-guides"):
+                    raise Exception(f"{category_path} is not a valid category. Please update config.yaml to use 'docs' or 'tutorials' instead.")
                 if self._convert_single_file(
-                        md_file, output_dir / 'content' / category_path,
-                        devsite_structure, dry_run):
+                        md_file, output_dir / 'content' / category_path, dry_run):
                     conversion_stats['converted_files'] += 1
                 else:
                     conversion_stats['error_files'] += 1
@@ -193,6 +195,11 @@ def _get_category_path(self, relative_path: Path) -> Path:
             return relative_path
 
         section_name = parts[0]
+    
+        # Orphan file like "help.md" -> put under Reference
+        if len(parts) == 1 and parts[0] == "help.md":
+            logger.info(f"Orphan file {parts[0]} detected, placing under 'reference' category")
+            return Path("docs") / Path("reference") / parts[0]
 
         # Look up the category for this section
         if section_name in self.config['content_mapping']:
@@ -201,12 +208,9 @@ def _get_category_path(self, relative_path: Path) -> Path:
 
             # Return path with category prefix
             return Path(category_type) / relative_path
-        
-        # Default to original path if no mapping found
-        return relative_path
+        raise Exception(f"No category mapping found for section '{section_name}', using original path")
 
-    def _convert_single_file(self, source_file: Path, output_file: Path,
-                             devsite_structure: Dict, dry_run: bool) -> bool:
+    def _convert_single_file(self, source_file: Path, output_file: Path, dry_run: bool) -> bool:
         """Convert a single markdown file from Devsite to Hugo format"""
         try:
             # Read source file
@@ -217,9 +221,7 @@ def _convert_single_file(self, source_file: Path, output_file: Path,
             frontmatter, body = self._parse_markdown_file(content)
 
             # Convert frontmatter to Hugo format
-            hugo_frontmatter = self._convert_frontmatter(
-                frontmatter, source_file, devsite_structure)
-
+            hugo_frontmatter = self._convert_frontmatter(frontmatter=frontmatter)
             # Extract title from H1 if not present in frontmatter
             title_from_h1 = None
             h1_match = re.search(r'^# (.+)$', body, re.MULTILINE)
@@ -277,8 +279,7 @@ def _parse_markdown_file(self, content: str) -> Tuple[Dict, str]:
 
         return {}, content
 
-    def _convert_frontmatter(self, frontmatter: Dict, source_file: Path,
-                             devsite_structure: Dict) -> Dict:
+    def _convert_frontmatter(self, frontmatter: Dict) -> Dict:
         """Convert Devsite frontmatter to Hugo format"""
         hugo_frontmatter = {}
 
@@ -296,7 +297,6 @@ def _convert_frontmatter(self, frontmatter: Dict, source_file: Path,
                 hugo_frontmatter[hugo_field] = frontmatter[devsite_field]
 
         # Add Hugo-specific fields
-        hugo_frontmatter['type'] = 'docs'  # Default to docs template
         hugo_frontmatter['weight'] = frontmatter.get('weight', 1)
 
         # Add title from H1 if not present in frontmatter
@@ -309,10 +309,6 @@ def _convert_frontmatter(self, frontmatter: Dict, source_file: Path,
         if 'title' in hugo_frontmatter and 'linkTitle' not in hugo_frontmatter:
             hugo_frontmatter['linkTitle'] = hugo_frontmatter['title']
 
-        # Add date if not present
-        if 'date' not in hugo_frontmatter:
-            hugo_frontmatter['date'] = '2024-01-01'
-
         return hugo_frontmatter
 
     def _convert_body_content(self, body: str) -> str:
@@ -640,10 +636,6 @@ def _generate_hugo_config(self, output_path: str) -> None:
         """Generate Hugo configuration file"""
         self.hugo_generator.generate_config(output_path)
 
-    def _generate_layouts(self, output_path: str) -> None:
-        """Generate Hugo layout templates"""
-        self.hugo_generator.generate_layouts(output_path)
-
     def _generate_section_indices(self, devsite_structure: Dict,
                                   output_path: str) -> None:
         """Generate _index.md files for Hugo sections"""

templates/hugo_config.yaml.jinja2

@@ -54,28 +54,6 @@ markup:
   math:
     enable: false
 
-# Menu configuration
-menu:
-  main:
-    - name: "Tutorials"
-      url: "/tutorials/"
-      weight: 10
-    - name: "How-To Guides"
-      url: "/how-to-guides/"
-      weight: 20
-    - name: "Explanations"
-      url: "/explanations/"
-      weight: 30
-    - name: "Reference"
-      url: "/reference/"
-      weight: 40
-    - name: "Community"
-      url: "/explanations/community/"
-      weight: 50
-    - name: "About"
-      url: "/explanations/about/"
-      weight: 60
-
 # Parameters for Docsy theme
 params:
   # Repository information
@@ -92,11 +70,7 @@ params:
   # Navigation configuration
   navigation:
     depth: 4
-    
-  # Footer configuration
-  footer:
-    enable: false
-    
+   
   # Disable math rendering
   katex:
     enable: false

templates/index_md.jinja2

@@ -1,27 +1,10 @@
 ---
 title: "{{ section.title }}"
-linkTitle: "{{ section.linkTitle | default(section.title) }}"
+{% if section.linkTitle %}linkTitle: "{{ section.linkTitle }}"{% endif %}
 {% if section.description %}description: "{{ section.description }}"{% endif %}
-type: "{{ section.type | default('docs') }}"
-weight: {{ section.weight | default(1) }}
+{% if section.type %}type: "{{ section.type }}"{% endif %}
+{% if section.weight%}weight: "{{ section.weight }}"{% endif %}
+{% if 'cascade' in section and section.cascade.type is defined %}
 cascade:
-  type: "{{ section.type | default('docs') }}"
+  type: "{{ section.cascade.type }}"{% endif %}
 ---
-
-# {{ section.title }}
-
-{% if section.description %}
-{{ section.description }}
-{% endif %}
-
-{% if section.overview %}
-{{ section.overview }}
-{% endif %}
-
-{% if section.subsections %}
-## Subsections
-
-{% for subsection in section.subsections %}
-- [{{ subsection.title }}]({{ subsection.path }}){% if subsection.description %} - {{ subsection.description }}{% endif %}
-{% endfor %}
-{% endif %}