Start mkdocs

.readthedocs.yml

@@ -3,10 +3,10 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "3.8"
+    python: "3.11"
 
-sphinx:
-  configuration: docs/conf.py
+mkdocs:
+  configuration: mkdocs.yml
 
 python:
   install:

docu/api/codegen/components.md

@@ -0,0 +1,9 @@
+# Codegen Components
+
+
+::: xsdata.codegen.transformer.ResourceTransformer
+::: xsdata.codegen.container.ClassContainer
+::: xsdata.codegen.analyzer.ClassAnalyzer
+::: xsdata.codegen.validator.ClassValidator
+::: xsdata.codegen.resolver.DependenciesResolver
+::: xsdata.codegen.writer.CodeWriter

docu/api/codegen/handlers.md

@@ -0,0 +1,76 @@
+# Codegen Handlers
+
+## Step Ungroup
+
+::: xsdata.codegen.handlers.FlattenAttributeGroups
+    options:
+      heading_level: 3
+
+## Step: Flatten
+
+::: xsdata.codegen.handlers.CalculateAttributePaths
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.FlattenClassExtensions
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.SanitizeEnumerationClass
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.UpdateAttributesEffectiveChoice
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.UnnestInnerClasses
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.AddAttributeSubstitutions
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.ProcessAttributeTypes
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.MergeAttributes
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.ProcessMixedContentClass
+    options:
+      heading_level: 3
+
+## Step: Sanitize
+
+::: xsdata.codegen.handlers.ResetAttributeSequences
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.RenameDuplicateAttributes
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.SanitizeAttributesDefaultValue
+    options:
+      heading_level: 3
+
+## Step: Resolve
+
+::: xsdata.codegen.handlers.ValidateAttributesOverrides
+    options:
+      heading_level: 3
+
+## Step: Finalize
+
+::: xsdata.codegen.handlers.VacuumInnerClasses
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.CreateCompoundFields
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.ResetAttributeSequenceNumbers
+    options:
+      heading_level: 3
+
+## Step: Designate
+
+::: xsdata.codegen.handlers.RenameDuplicateClasses
+    options:
+      heading_level: 3
+::: xsdata.codegen.handlers.DesignateClassPackages
+    options:
+      heading_level: 3

docu/api/codegen/mappers.md

@@ -0,0 +1,8 @@
+# Codegen Mappers
+
+
+::: xsdata.codegen.mappers.SchemaMapper
+::: xsdata.codegen.mappers.DefinitionsMapper
+::: xsdata.codegen.mappers.DtdMapper
+::: xsdata.codegen.mappers.ElementMapper
+::: xsdata.codegen.mappers.DictMapper

docu/api/codegen/parsers.md

@@ -0,0 +1,6 @@
+# Codegen Parsers
+
+
+::: xsdata.codegen.parsers.SchemaParser
+::: xsdata.codegen.parsers.DefinitionsParser
+::: xsdata.codegen.parsers.DtdParser

docu/cli.md

@@ -0,0 +1,131 @@
+# Command Line
+
+Make sure the cli requirements are installed.
+
+```console
+pip install xsdata[cli]
+```
+
+```bash exec="1" source="tabbed-left" returncode="0"
+xsdata --help
+```
+
+
+## Generate Code
+
+```bash exec="1" source="tabbed-left" returncode="0"
+xsdata generate --help
+```
+
+```console title="Scan directory for xsd, dtd, wsdl, xml or json files"
+xsdata amadeus/schemas --package amadeus.models
+```
+
+```console title="Convert a local schema"
+xsdata air_v48_0/AirReqRsp.xsd --package travelport.models
+```
+
+
+```console title="Convert a remote schema"
+xsdata http://www.gstatic.com/localfeed/local_feed.xsd --package feeds
+```
+
+```console title="Convert a remote xml file and print output"
+xsdata https://musicbrainz.org/ws/2/artist/1f9df192-a621-4f54-8850-2c5373b7eac9 --print
+```
+
+Output plugins
+--------------
+
+- `PlantUML <https://github.com/tefra/xsdata-plantuml>`_ class diagrams
+
+
+Circular imports
+----------------
+
+Python is vulnerable to xsd circular imports. xsData by default groups all classes
+by the schema location they are defined. This works well for schemas that avoid circular
+imports. If you get import errors you should try one of the alternative structure
+styles.
+
+**clusters**
+
+This style will identify the strongly connected classes and will group them together,
+creating as many modules as possible. The modules are named after the the main class
+of the group.
+
+.. code-block:: console
+
+    $ xsdata schema.xsd --package models --structure-style clusters
+
+
+**namespaces**
+
+This style will group classes by the target namespace they were originally defined. It
+works well when the types of a namespace are spread across multiple schemas eg.
+type substitutions, redefines.
+
+.. code-block:: console
+
+    $ xsdata schema.xsd --package models --structure-style namespaces
+
+
+Since v21.8, the generator converts namespaces to packages similar to jaxb in order
+to facilitate runs against multiple schemas from the same vendor.
+
+.. list-table::
+    :widths: 20 20
+    :header-rows: 1
+
+    * - Examples (before naming conventions)
+      -
+    * - http://www.w3.org/XML/1998/namespace
+      - org.w3.xml.1998.namespace
+    * - myNS.tempuri.org
+      - org.tempuri.myNS
+    * - urn:xmlns:25hoursaday-com:address
+      - com.25hoursaday.address
+
+
+**namespace-clusters**
+
+This style combines the clusters and the namespace styles. It will fail if there
+are strongly connected classes in the same graph from different namespaces.
+
+.. code-block:: console
+
+    $ xsdata schema.xsd --package models --structure-style namespace-clusters
+
+
+**single-package**
+
+This style will group all classes together into a single package eliminating imports
+altogether.
+
+.. code-block:: console
+
+    $ xsdata schema.xsd --package models --structure-style single-package
+
+
+Initialize Config
+=================
+
+Initialize a project configuration with more advanced features, see
+:ref:`more <Generator Config>`.
+
+.. cli:: xsdata init-config --help
+
+.. code-block:: console
+
+    $ xsdata amadeus/schemas --config amadeus/.xsdata.xml
+
+
+Download Schemas
+================
+
+.. cli:: xsdata download --help
+
+.. admonition:: Examples
+    :class: hint
+
+    Check the :doc:`examples` and the `samples repo <https://github.com/tefra/xsdata-samples>`_ for more ✨✨✨

docu/codegen/architecture.md

@@ -0,0 +1,129 @@
+# Architecture
+
+
+``` mermaid
+graph LR
+    A[Load Resources] --> B(Parse transfer objects)
+    B --> C[Convert to classes]
+    C --> D[Analyze classes]
+    D--> E[Write Output]
+```
+
+
+## Load Resource
+
+The code generator accepts URIs indicating either local or remote file locations.
+
+The resource type (xsd, wsdl, dtd, xml, json) is identified based on the file extension,
+if present. If the resource lacks an extension, the loader will attempt to locate specific
+syntax markings associated with the resource type.
+
+If a resource cannot be accessed, a warning is issued, and the program continues its normal flow.
+
+In the case of circular imports, resources are loaded only once.
+
+## Parse transfer objects
+
+A resource-specific parser is utilized to bind document information to transfer objects.
+Additionally, the parsers are responsible for assigning common values required for later
+analysis, such as locations, a namespace prefix-URI map, and common namespaces like
+xsi and xlink.
+
+
+## Convert to classes
+
+A resource-specific parser is utilized to convert the transfer objects to codegen
+classes. These mappers encapsulate the pertinent logic detailing how the resource
+types should be interpreted.
+
+
+## Analyze classes
+
+```mermaid
+graph LR
+    A[Validate classes] --> B(Process classes)
+    B --> C[Validate class references]
+```
+
+### Validate Classes
+
+- Remove types with unknown references
+```xml
+<xs:element name="root" ref="xs:missingOrUnknown"/>
+```
+
+- Remove duplicate types: Keep the last definition
+```xml
+<xs:element name="root" ref="RootType"/>
+<xs:element name="root" ref="RootType"/>
+```
+
+- Remove duplicate overriden types:
+```xml
+<xs:override schemaLocation="over005a.xsd">
+    <xs:attribute name="code" type="xs:date"/>
+</xs:override>
+```
+- Merge redefined types:
+```xml
+<xs:redefine schemaLocation="schZ006.xsd">
+    <xs:group name="GCustomDimProps">
+        <xs:sequence>
+            <xs:element name="DisplayInfo"	type="xs:unsignedInt"/>
+        </xs:sequence>
+    </xs:group>
+</xs:redefine>
+```
+
+### Analyze Classes
+
+This procedure consists of several steps, all classes have
+to pass through each step before next one starts. The
+order of the steps is very important!
+
+#### Step Ungroup
+
+- Flatten group attrs
+
+#### Step: Flatten
+
+- Calculate min/mac occur restrictions
+- Flatten class extensions
+- Sanitize enumerations
+- Detect implied repeated choices
+- Unnest inner classes
+- Apply substitution groups
+- Process field types
+- Merge duplicate fields
+- Process mixed content classes
+
+### Step: Filter
+
+- Filter generated classes
+
+#### Step: Sanitize
+
+- Unset unnecessary sequence numbers
+- Rename duplicate attrs
+- Sanitize default values
+
+#### Step: Resolve
+
+- Validate attr overrides
+
+#### Step: Finalize
+
+- Vacuum orphan inner classes
+- Create compound fields
+- Re-Index sequence numbers
+
+#### Step: Designate
+
+- Rename duplicate classes
+- Assign classes to modules and packages
+
+
+## Convert to classes
+
+This process passes the control to register output writer
+and writes the output by using jinja templates.