Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: plotly/plotly.js
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: master
Choose a base ref
...
head repository: plotly/plotly.js
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: mkdocs-conversion
Choose a head ref
Checking mergeability… Don’t worry, you can still create the pull request.
  • 4 commits
  • 23 files changed
  • 1 contributor

Commits on Dec 6, 2024

  1. feat: use MkDocs to generate documentation from plot-schema.json

    1.  Copy `make_ref_pages.py` from graphing-library-docs repository to
        create `bin/make_ref_pages.py` and then refactor to generate
        Markdown stubs for documentation pages.
    
    1.  Write `bin/gen.py` to generate HTML pages from the Markdown stubs
        using the Jinja templates in the `theme` directory for debugging.
    
    1.  Convert Jekyll templates from graphing-library-docs repository to
        Jinja and store in `theme` directory.
    
    1.  Write `requirements.txt` file to install required Python packages.
        -   `beautifulsoup4`: for HTML manipulation
        -   `html5validator`: to validate generated HTML
        -   `jinja2`: for manual template expansion
        -   `mkdocs`: for website generation
        -   `mkdocs-exclude`: to exclude `.jinja` files from generation
        -   `python-frontmatter`: for manual template expansion
        -   `ruff`: for checking `bin` scripts
    
    1.  Write `Makefile` to automate build and test.
    
    1.  Modify documentation comments in some JavaScript files to remove
        stray backticks.
    
    Notes:
    
    1.  As of the time of this commit, the `mkdocs_data_loader` plugin
        must be installed directly from a `.whl` file or similar. It will
        be added to `requirements.txt` once the plugin is on PyPI.
    
    1.  Jinja does not expand directives in Markdown files; it only
        expands those it finds in template `.jinja` files. Because of
        this, the Markdown stubs generated by `bin/make_ref_pages.py` have
        YAML headers but no bodies.
    
    1.  The logic to set the `details` variable in `theme/main.jinja` is
        copied from the original Jekyll templates and modified by trial
        and error to produce (what appears to be) the right answer.  If
        pages contain extra information, or if information is missing, the
        most likely cause is an error here.
    
    1.  At the time of this commit, no styling is applied to the generated
        pages and they do not contain headers, footers, or navigation.
        All of this should be added once a general site theme is developed.
    
    1.  `bin/gen.py` defines a `backtick` filter to convert backtick'd
        pieces of text to `<code>` blocks. This is currently *not* used in
        the Jinja templates because (a) the existing documentation
        includes the backticks as-is and (b) I couldn't be bothered to
        figure out how to add it to MkDocs.
    gvwilson committed Dec 6, 2024
    Copy the full SHA
    2ac2664 View commit details

Commits on Dec 9, 2024

  1. feat: modify to work with mkdocs-material as well

    1.  Move configuration `mkdocs.yml` to `mkdocs-vanilla.yml`.
    1.  Move logic to set `details` from `theme/main.jinja` to `theme/attribute.jinja`
        where it is actually used.
    1.  Create new `mkdocs-material.yml` configuration file with mkdocs-material settings.
    1.  Change configuration to load overrides from `overrides` directory.
    1.  Copy template files *without* `main.jinja` to `overrides` directory.
    1.  Modify `Makefile` to build `mkdocs-vanilla` (our own) or `mkdocs-material`.
    gvwilson committed Dec 9, 2024
    Copy the full SHA
    86f5f55 View commit details
  2. Copy the full SHA
    fd14bf6 View commit details

Commits on Jan 27, 2025

  1. Copy the full SHA
    b4c4f14 View commit details
Loading