Relocation of the documention (final solution) #50466
Labels
No Label
Meta
Good First Issue
Module
Animation & Rigging
Module
Core
Module
Development Management
Module
Eevee & Viewport
Module
Grease Pencil
Module
Modeling
Module
Nodes & Physics
Module
Pipeline, Assets & IO
Module
Platforms, Builds, Tests & Devices
Module
Python API
Module
Rendering & Cycles
Module
Sculpt, Paint & Texture
Module
User Interface
Module
VFX & Video
Priority
High
Priority
Low
Priority
Normal
Status
Archived
Status
Confirmed
Status
Duplicate
Status
Needs Information from Developers
Status
Needs Information from User
Status
Needs Triage
Status
Resolved
Type
Bug
Type
Design
Type
Known Issue
Type
Patch
Type
Report
Type
To Do
No Milestone
No project
No Assignees
8 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: blender/blender-manual#50466
Loading…
Reference in New Issue
No description provided.
Delete Branch "%!s(<nil>)"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Currently, our documentation is all over the place:
And we are not following this industry standard of having one place to have all the documentation.
I purpose that we move documentation to this base URL: docs.blender.org
from there we can move the documentation:
This would allow us to separate its integration on blender.org and move it to its own jail
Most of the change can happen right away and will not affect users, for we can setup redirects.
The biggest change is that we need to design a home page for docs.blender.org
Aside from this documentation from other projects should be added to the rBM?
Changed status to: 'Open'
Added subscribers: @Blendify, @fsiddi, @dmcgrath, @Ton
Added subscriber: @JohnRoper
I would be willing to design a home page for it using the Blender web assets.
That would be helpful thank you John
Here is the design I am working on. #50467
The idea has been floating around for a while (I think possible from Campbell and I discussing it?). Either way, I am obviously for the idea. A bit of the reasons I had last we discussed were security related more than anything. Here are some of the valid points that I could find that we've discussed in the past already, to try bring things into one place for us:
As you can see, we have a few other things to consider aside from the domain, such as versioning.
After some considerations, here is what we can do:
The mockup made by @JohnRoper is nice, and we are likely going to implement it directly within blender.org
This involves several steps and is mostly backend work. High priority is to keep all existing links working. More discussion can happen in #blenderwiki
So far I have the following things done for this task:
I spoke with mont29 in IRC and had him update his script paths for /api/, so all new updates should go to the live version at https:*docs.blender.org/api/ with the old location at https:*www.blender.org/api/ being a stale copy. At some point when we are "ready", this old location will be replaced with redirects to the new location. The same will happen with the /manual/ path, but since it is an automated script, it's not a big deal to serve both locations.
@dmcgrath @fsiddi If you can give me the info or create a new repository here for me I can upload the code for my design for the homepage.
Added subscriber: @Sergey
That is something that @Sergey deals with afaik, but maybe you could just use github in the meantime?
Just curious, but was this html for the docs.blender.org landing page? Or something else?
yes. It is just html code
@JohnRoper so where is the code? I was hoping to at least get it in place :p
Here is some code @dmcgrath https://github.com/armadillica/docs.blender.org
We can decide what to do with this repo later on (maybe can be part of something larger).
Cool, thanks! I put it in place. Probably could use similar for /manual/ and /api/ I guess, but /api/ would be tricky just cause of all the links.
Anyway, looks great, thanks! o/
@fsiddi @dmcgrath Code added to that github (pull request)
Looks great guys! I think that the docs.blender.org should also be added to the header bar. Any thoughts? This would give the docs more traffic.
Thanks @JohnRoper, but that is controlled by Francesco I think. I would probably also suggest using .html as the extension, as opposed to .htm so we don't have to fiddle with the DirectoryIndex configuration.
@Blendify I would probably hold off adding anything to the header on the other sites until it is official "live". Speaking of which, I guess we can think about actually switching things soon?
@fsiddi Oh, I almost forgot, but that index.htm file also has a blender.org Google Analytics id. Not sure if that was intended.
Added subscriber: @Tobias
I absolutely see no need for a landing page (https://docs.blender.org/manual/)
I would suggest to rather:
I think we should add something like read the docs. I have looked into but have had a hard time being able to port it to our setup.
That's fine by me, as it saves worrying about a landing page. But where should we redirect people that visit /manual/? I can assume that we would default them to /manual/en/ via a temp 302 redirect, which in turn will redirect to /manual/en/dev/? I think that last one is a 301 atm, but I can change that to a 302 so it at least allows us to change it quickly to something else, down the road.
Added subscriber: @JulianEisel
In general I'm a big fan of gathering all our services on more centralized places, making it easier to find and access them. So big +1 for the idea of bringing all the docs to a unified docs.blender.org domain.
The way we currently deliver docs is a mess - especially those on the wiki. So I'd really like to see some solid planning on how to organize things before we move forward.
Main reason I'm saying that is because the wiki wasn't mentioned here yet, and I think it should align well with the plans discussed here. We should either move it to docs.blender.org too, or agree to keep it separate on wiki.blender.org - at the cost of breaking the rule of a centralized location for docs. (Also see #48096.)
Another thing I'm quite vary about:
/api/
is pretty misleading here. What we are talking about is the Blender Python API (BPY API), Blender has many more APIs (mainly in C/C++ code). Adocs.blender.org/api/
page would be a quite nice trap for people searching for C/C++ code docs.Two things we could do:
docs.blender.org/python_api/
insteaddocs.blender.org/api/
. These would likely be automatically generated docs using [Doxygen ]]. We already use markup comments for it everywhere in code and I know that various people actually generate API docs from this (check this old [http:*www.letworyinteractive.com/blendercode/modules.html | 2.61 example ).I actually lean towards the second one, even if that means more work and increased maintenance burden once again. It would be interesting to see if such docs help people getting into the source code.
@JulianEisel I think that that is a good idea
Added subscriber: @mont29
Not sure I like /python_api/ much, just for url neatness. I think something like /python/api/ or similar looks better than having hyphens and underscores in the URL.
Today I activated the redirect from https:*www.blender.org/api/ to https:*docs.blender.org/api/. As of now, we are "live" for API docs (@mont29 was already set to update the new location, might as well make it active).
I also added a HEADER.html and FOOTER.html to the docs.blender.org git repo that is used to wrap the directory listing at https://docs.blender.org/api/ in the current blender theme. It needs some CSS love, but perhaps @fsiddi would be better off handling this as it is his theme. Just give me a poke when you need the repo on the webserver updated.
@JulianEisel please let’s not start calling all and everything 'API'!
Blender does not have any C api really, an API would imply Blender can be used as a library, or use some kind of runtime-loadable C/C++ plugins, which it cannot (and we do not seek anything like that currently). Even though it would be great to document more our code structure etc., this is no API at all (or, you can call it private APIs if you want), and imho does not pertain to
docs
area, more todev
one. The same goes with C++ of course.To summarize my point: let’s not document Blender’s source code into
docs
namespace, imho it does not pertain here, but indev
namespace.I made a quick sitemap and updated the robots file
Both were added to the git repo. Same update poke me rules apply :)
As well, the old https:*www.blender.org/manual/ paths now redirect to https:*docs.blender.org/manual/. The blender code and existing manual links should be updated and the old path considered defunct.
Thanks for all the replies and inputs! Here is a summary:
/api
for the python API (there will be no other API in the foreseeable future)Here is a further discussion point: to make API urls more friendly I would consider the follow structure
/api/<version>/
, for example:/api/2.71a
/api/2.71
/api/2.71rc1
/api/2.71rc1
All existing links should redirect correctly, so this is potentially quite some work. Just wanna bring it up because a more semantic numbering would be nice. @dmcgrath do you think this is doable?
Hey @fsiddi
I assume that you are the CSS guru of the group, and was hoping that we could take care of tweaks to the CSS for the
/api
path together? Of course I am here to get the changes live and tested with you! Let me know when you want to get together and knock it out of the park, etc.The
/api/<version>/
stuff is up to the developers, IMHO; I have no dogs in this fight. Ideally I think the actual naming should be something the core developers chime in on though, not me. My only advice is to do it so that it matches existing file and directory naming conventions, but I don't know what conventions you are. Were you proposing to change existing filenames and set up redirects? Or just do this for new directories? If anything, @mont29 could setup symlinks for existing directories to allow old and new locations to exist, and save any work at all on the back end. Then just make sure that new stuff adhears to the new standard. Thoughts?If you must move stuff, I can work with @mont29 to ease some of the rsync stuff by working lockstep with him to rename paths on the shell so that he doesn't have to re-upload hundreds of megabytes again for something that just changed paths, but it should be him to make the change or else he will just blow away all of the work done on the server side.Plus he is the actual maintainer of the
/api
stuff, I think?I talked to Campbell and we decided that there is no need for subversions of the API. We should follow this layout:
@Blendify out of curiosity, why the underscore? Is that common practice for versioning, in blender or anywhere else?
Not really but do not like https:*docs.blender.org/api/278a/ a guess we could also do https:*docs.blender.org/api/2.78a/ but I do not know if servers and other os's like that.
Well, as I said before, up to you guys. The server shouldn't care about a period in the path for a directory though, just an FYI.
Dots in file/dir names are not an issue on Unix since ages ;)
Agree name should be made simpler, how exactly is not that important imho, as long as it can be easily used in automated processes?
Regarding current (daily build) API, I would rather use branches names (as currently, so https://docs.blender.org/api/master/ ), also because we may want other branches's API doc at some point (thinking about blender2.8 here for near future) - and find it clearer what is documenting what that way.
@dmcgrath would definitively rather use symlinks, than renaming all dirs here (and doing some redirects on server side), sounds much, much simpler. :)
I think he meant more like a server treating something like
foo.blah
as some weird extension in Apache using some weird mime type or extension handler. At least that is what I took away from it.Glad to hear @mont29. Anything that saves us from having to micromanage a bazillion files is good in my book :)
@mont29, my point is simply that
docs.blender.org/api/
is far too vague and may be misleading. We do have many APIs, it doesn't matter if they're internal/private or external. The thing is, one person clicking ondocs.blender.org/api/
might expect to see an API documentation for C/C++ plugins, another one might expect to see the documentation of the internal APIs and another one might expect it to show the Python API documentation.The URLs and sitemap structure should make it clear what kind of APIs and corresponding docs are available.
Also, please consider my point regarding the Wiki. Why should all docs except of Blender core development ones be on docs.blender.org ? If there are good reasons for it, I'd be fine with leaving them in the wiki, but ideally we'd have a central place for all documentation - manual, python development and Blender core development.
How about a sitemap like this:
docs.blender.org/manual/
docs.blender.org/bpy/
**
docs.blender.org/bpy/introduction/
**
docs.blender.org/bpy/process/
**
docs.blender.org/bpy/api/
** ...
docs.blender.org/dev/
**
docs.blender.org/dev/process/
**
docs.blender.org/dev/projects/
**
docs.blender.org/dev/source/
***
docs.blender.org/dev/source/overview/
***
docs.blender.org/dev/source/architecture/
***
docs.blender.org/dev/source/api/
*** ...
docs.blender.org/users/
?)De facto, docs.blender.org would be a proper replacement for this page: https:*wiki.blender.org/index.php/Main_Page.
I'm not proposing to move the Wiki to docs.blender.org right now, but I'm asking for a well-considered plan before we start making changes and spreading links on the web.
It's really great so see so much attention put into documentation and I think our infrastructure would become far less confusing by having a central domain for all documentation.
I can see some good points here. I kinda like the idea of having a wiki in docs as well, but is this what we really want? We could move https:*en.blender.org/ under https:*docs.blender.org/wiki/ (even as a test to see how it works) and have https://docs.blender.org/ redirect to
/wiki/
by default, I suppose. Your call.I do agree, however, that we should avoid spreading links all over, and then having those links be removed/changed.
I do not really think that is what he meant. I think I meant that docs.blender.org would be a replacement landing page instead of the one found at https://wiki.blender.org/index.php/Main_Page
Do you mean make the current page the new Main_Page for https:*wiki.blender.org/? Or do you mean move the wiki to the "root" path on https:*doc.blender.org/?
I don’t think dev docs and user docs are same thing, and I don’t think they shall share the same namespace.
User doc has some well-structured, hopefully high-quality expectations. And I do include public API docs here. It has an expected audience of tens of thousands if not millions of people, has a role of “public representation” to some extent, and can be potentially contributed by thousands of users who know how to use Blender. As such, it needs a well structured, and rather stable content, and it is worth spending time on it also on its look/aspect sides, ensure spelling etc. is correct, translate it to other languages… ==> Generated static html (currently, at least).
Dev docs are only for the few people that need to understand the internals of Blender, and for those working on its development. It has an expected audience a hundreds, thousands at most people, very low number of potential writers typically, who often have very few time for it. It is intended to be used for technical descriptions of projects, quick overview of how some code areas work, a place for developers and stakeholders to write whatever they want… As such, we need a very quick and easy, loosely structured way to edit it, and do not care that much about shiny styling, crispy spelling, and so on. ==> wiki.
So I really do not think mixing both of those in a same 'namespace' is a good idea. Too bad developer.blender.org is already taken by phab (though maybe we could use
developer.blender.org/wiki
for the wiki eg?).Note that I would not be against some well-structured, high-quality docs about Blender internals in docs.blender.org. It’s just that, afaik, we do not have any currently, and I don’t expect anyone to have the (huge) amount of free time to work on such a project in near future?
Now, regarding
/bpy/
instead of/api/
… Am not sure. I see the point (bpy is indeed more accurate than api), but for now only public API is bpy. So I don’t think it really matters currently. Should we have other public APIs in the future, we could always move current/api/
into/api/bpy/
, and add new ones under same/api/
section…I think that there is a built-in phabricator wiki. Not to say we should switch to that (@Sergey would know best here), but it would conflict with the path a bit potentially?
I admit that it does seem a little odd to have 3 items listed on the landing page for
docs.blender.org
now (api/manual/wiki), but one of them is on another domain.None of these, I was just pointing out that the entry point to all Blender documentation currently is https:*wiki.blender.org/, and in future with the new docs infrastructure it would be https:*docs.blender.org/. Both sites can stay as they are for now (as long as we keep wiki.blender.org), just saying ;)
I don't see why we shouldn't have both under the same domain though? https://docs.blender.org/ would be split into some main categories. These categories link to completely different kind of docs anyway (e.g. Manual vs. BPY API docs), I don't see an issue with having the dev docs there as well, just because they are less polished?
Also, I'd consider the Python API docs far less polished as the manual (contains spelling mistakes, [totally unhelpful descriptions ]], [ https:*docs.blender.org/api/blender_python_api_current/bpy.types.Panel.html?highlight=xxx#bpy.types.Panel.text | XXXes , ...). So following your argumentation the Python API had to stay separate from docs.blender.org as well ;)
Note that I'm not proposing to move the dev docs out of the wiki, but just to move them to a different URN to make our infrastructure less confusing - e.g.
wiki.blender.org/Dev:foo/
->docs.blender.org/dev/foo/
That's the thing, we shouldn't just use
/api/
for Python docs now and decide later to move them to something else while repurposing/api/
for something different (eg. landing page for public APIs). We'd break all existing links to/api/
on the web. Hence my call for choosing namespaces carefully :)In my idea, also non-API Python docs like this would be under
/bpy/
. That's why I'd preferdocs.blender.org/bpy/...
as opposed todocs.blender.org/api/...
.@dmcgrath I'm up for some CSS tweaks in the upcoming days, I'll message you directly, also about symlinks and renames.
Regarding
/api
vs/bpy
, I see your point @JulianEisel, but the chances of getting any other API next to it in the future are close to none (and can be solved by adding a new language after the version, like/api/2.80/python/
).Further:
/api/2.78b/
(/api
url prefix and dot-separated digits are a standard in API documentation URLs)Priority should be to finalize (user) API and manual URLs and pages.
I don't think that you don't want to have a wiki at the root path like
docs.blender.org/
. It's not recommended officially, IIRC, and it would just make things a headache when we add stuff that conflicts in the same namespace (ie: we have/manual
and/api
and then some user in the wiki creates such a path). At the absolute minimum, the wiki should be atdocs.blender.org/wiki/
with a redirect from the landing page redirecting to it on aLocationMatch
of "^/$". At least that is my advice.@fsiddi sounds good. Chat with you later o/
EDIT: Well, not technically a
LocationMatch
, but aRewriteRule
. Pretty much the same idea in this context, however.Added subscriber: @francesco
@fsiddi re
/api/
, agreed, will do the change in names soonish :)Added subscriber: @RayMairlot
So, finally found time to update API doc layout, should now match what we decided above.
Also note that I added an
/api/blender2.8/
entry, think it’s time we get some easily accessible doc about that one too. ;)Changed status from 'Open' to: 'Resolved'
Thanks for everyone who helped move this over.