New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Versioned Documentation #71

Open
froschdesign opened this Issue Dec 1, 2018 · 3 comments

Comments

Projects
None yet
3 participants
@froschdesign
Member

froschdesign commented Dec 1, 2018

Problem

Some component documentations already includes descriptions and pages for different component versions. This ends up in a very long sub-navigation and duplications of navigations entries.

Example

zend-expressive with 3 versions: https://docs.zendframework.com/zend-expressive

Goals for Improvement

  • add a version selector
  • only show pages of the currently selected version in the sub-navigation
  • output a notice if the currently selected version is not the latest
  • backward compatibility:
    • no changes in URLs
    • without any changes (in the MkDocs configuration), the result of the rendering must be the same as before

Suggestion

The current idea is based on an extension of the MkDocs configuration file (mkdocs.yml).

New is the extra level in pages for the version number and the section extra.

Example (excerpt)

docs_dir: docs/book
site_dir: docs/html
pages:
    - Home: index.md
    - v3:
      - "Quick Start": v3/quick-start.md
      - Hydrators:
        - "ArraySerializable": v3/hydrators/array-serializable.md
        - "ObjectProperty": v3/hydrators/object-property.md
        - "Reflection": v3/hydrators/reflection.md
        - "ClassMethods": v3/hydrators/class-methods.md
        - "Delegating": v3/hydrators/delegating.md
        - "Aggregate": v3/hydrators/aggregate.md
      - Strategies:
        - 
      - "Application Integration":
        - "Usage in a zend-mvc-based Application": v3/application-integration/zend-mvc.md
      - Migration:
        - "Migration from version 2": v3/migration.md
    - v2:
      - "Quick Start": v2/quick-start.md
      - Reference:
        - "Filters": v2/filter.md
        - 
    - "_hidden-legacy-page-links":
        - "_quick_start": quick-start.md
        - 
site_name: zend-hydrator
site_description: "Serialize objects to arrays, and vice versa"
repo_url: 'https://github.com/zendframework/zend-hydrator'
markdown_extensions:
  - markdown.extensions.codehilite:
      use_pygments: False
edit_uri: edit/master/${DOCS_DIR}/
extra:
  current_version: v3
  versions:
    - v3
    - v2

Screenshots

screenshot_2018-12-01 home - zend-hydrator
screenshot_2018-12-01 quick start - zend-hydrator

To-do

  • Update the Jinja2 templates
  • Add CSS for version selector

Comments and suggestions are welcome!

@froschdesign

This comment has been minimized.

Member

froschdesign commented Dec 1, 2018

@xtreamwayz

This comment has been minimized.

Member

xtreamwayz commented Dec 1, 2018

Where is the PR so I can merge it now.

@weierophinney

This comment has been minimized.

Member

weierophinney commented Dec 5, 2018

Totally want this. 👍

@froschdesign froschdesign added this to the 0.7.0 milestone Dec 8, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment