New Developer Documentation Platform: Navigation #116053

New Issue

Julian Eisel · 2023-12-11T17:59:02+01:00

Julian Eisel commented

2023-12-11 17:59:02 +01:00

Roughly, the navigation could look like the following:

Home
Developer Handbook
- New Developer Introduction
- Communication
- Modules
- Process
- Building Blender
- Style Guides
- Tools
- FAQ
Features
- Asset System
- Cycles
- EEVEE & Viewport
- User Interface
- Infrastructure
- ...
Human Interface Guidelines
Release Notes
More...
- GSoC
- GSoD
Contribute

Mockups

We will have to build our own navigation UI. Idea is to use a navigation header for this. Here are some ideas on how this could look like.

Idea 1: Material for MkDocs based
This is based on the default tabbed navigation of Material for MkDocs (but extended to support dropdown selectors):

Idea 2: blender.org based
Based on the navigation on blender.org, e.g. see https://www.blender.org/download/lts/.:

Idea 3: blender.org based, variation with pulldown menus
More loosely based on the blender.org navigation, but still using pulldowns menus:

Roughly, the navigation could look like the following: - Home - Developer Handbook - New Developer Introduction - Communication - Modules - Process - Building Blender - Style Guides - Tools - FAQ - Features - Asset System - Cycles - EEVEE & Viewport - User Interface - Infrastructure - ... - Human Interface Guidelines - Release Notes - More... - GSoC - GSoD - Contribute ## Mockups We will have to build our own navigation UI. Idea is to use a navigation header for this. Here are some ideas on how this could look like. **Idea 1: Material for MkDocs based** This is based on the default tabbed navigation of Material for MkDocs (but extended to support dropdown selectors): ![](https://projects.blender.org/attachments/85804cb6-d8f4-4b9c-8793-02e7a54263db) **Idea 2: blender.org based** Based on the navigation on blender.org, e.g. see https://www.blender.org/download/lts/.: ![](https://projects.blender.org/attachments/ac76effc-751f-4dc1-895b-664f3c86bf1b) **Idea 3: blender.org based, variation with pulldown menus** More loosely based on the blender.org navigation, but still using pulldowns menus: ![](https://projects.blender.org/attachments/66c6bd6a-d3ff-4c8f-9cb9-d33c0346ed66)

devdocs-nav-mockup-blender-org.png

258 KiB

devdocs-nav-mockup-blender-org-variation.png

267 KiB

devdocs-nav-mockup-material-for-mkdocs-based.png

523 KiB

Julian Eisel added the

Type

Design

label 2023-12-11 17:59:02 +01:00

Julian Eisel added this to the Developer Documentation project 2023-12-11 17:59:04 +01:00

Brecht Van Lommel commented

2023-12-11 19:32:32 +01:00

In Idea 2, I expect we will run into horizontal space issues under Features pretty quickly. Idea 1 or 3, or just an intermediate page with links would be fine with me.

For the developer handbook, maybe reshuffling content like this would be more clear. Subsections are only indicative of type of content, not a complete list.

Getting Started
- Building
- Contributing
- Communication Channels
Building
Tools
- Debugging
- Profiling
- IDEs
- Git
Guidelines
- C/C++ Style
- Commit Messages
- Compatibility
- Code of Conduct
Bug Triaging
Release Cycle
- Checklist
- LTS
- Stabilizing Branch
Organization
- Admins
- Modules
- Projects
FAQ

In Idea 2, I expect we will run into horizontal space issues under Features pretty quickly. Idea 1 or 3, or just an intermediate page with links would be fine with me. For the developer handbook, maybe reshuffling content like this would be more clear. Subsections are only indicative of type of content, not a complete list. * Getting Started * Building * Contributing * Communication Channels * Building * Tools * Debugging * Profiling * IDEs * Git * Guidelines * C/C++ Style * Commit Messages * Compatibility * Code of Conduct * Bug Triaging * Release Cycle * Checklist * LTS * Stabilizing Branch * Organization * Admins * Modules * Projects * FAQ

Julian Eisel commented

2023-12-20 12:12:19 +01:00

I think Organization should be higher up the list. Especially the module page is important to understand how things work at Blender.

Tools I'd put lower, this is rather specific information. Not sure Git should be in there, it's not really a tool, more like the core of our pipeline. At least some information like how to set up commit access should probably be under Getting Started > Contributing. Tools could still contain an Advanced Git Workflow page or such.

Testing could be its own section as well.

I think _Organization_ should be higher up the list. Especially the module page is important to understand how things work at Blender. _Tools_ I'd put lower, this is rather specific information. Not sure _Git_ should be in there, it's not really a tool, more like the core of our pipeline. At least some information like how to set up commit access should probably be under _Getting Started_ > _Contributing_. _Tools_ could still contain an _Advanced Git Workflow_ page or such. _Testing_ could be its own section as well.

Brecht Van Lommel commented

2023-12-20 14:16:16 +01:00

That all sounds good to me.

Julian Eisel commented

2023-12-20 14:22:55 +01:00

Refining/tweaking it a bit more, here's a more detailed proposal for a few sections:

Getting Started:
- New Developers: (Old New Developer Overview page as index.md)
  - Advice for new Developers
  - Good First Issues
  - Resources
- Communication Channels:
  - Chat
  - Code of Conduct
  - Copyright Rules
- Building Blender:
  - Linux
  - macOS
  - Windows
  - Build Options (rename to make Utility?)
  - Resolving build errors
- Contributing:
  - Pull Requests
- Environment:
  - VSCode
  - XCode
  - ...
...
Guidelines:
- ...
- For All Developers (bit of a weird page, might want to merge this with the commit rights page)
- Reverting Commits
Building Blender (Advanced):
- Cycles:
  - GPU Binaries
  - Building Cycles as Hydra Delegate
- Release Environments:
  - Cent OS 7
  - Rocky 8
...

Refining/tweaking it a bit more, here's a more detailed proposal for a few sections: - [x] Getting Started: - [x] New Developers: (Old New Developer Overview page as index.md) - Advice for new Developers - Good First Issues - Resources - [x] Communication Channels: - Chat - Code of Conduct - Copyright Rules - [x] Building Blender: - Linux - macOS - Windows - Build Options (rename to _`make` Utility_?) - Resolving build errors - [x] Contributing: - Pull Requests - [x] Environment: - VSCode - XCode - ... - ... - Guidelines: - ... - For All Developers (bit of a weird page, might want to merge this with the commit rights page) - Reverting Commits - Building Blender (Advanced): - Cycles: - GPU Binaries - Building Cycles as Hydra Delegate - Release Environments: - Cent OS 7 - Rocky 8 - ...

Brecht Van Lommel commented

2024-01-29 16:01:50 +01:00

The migration is completed, see #116055.

Brecht Van Lommel closed this issue

2024-01-29 16:01:55 +01:00

Blender Bot added the

Status

Archived

label 2024-01-29 16:01:58 +01:00

Sign in to join this conversation.