[Bf-docboard-svn] bf-manual: [9403] trunk/blender_docs: Cleanup: Move contribute guide to own subfolder

Aaron Carlisle noreply at blender.org
Tue Jul 12 03:20:35 CEST 2022 

Revision: 9403
          https://developer.blender.org/rBM9403
Author:   Blendify
Date:     2022-07-12 03:20:35 +0200 (Tue, 12 Jul 2022)
Log Message:
-----------
Cleanup: Move contribute guide to own subfolder

Add a redirect to avoid and broken links

Fixes T99325

Modified Paths:
--------------
    trunk/blender_docs/manual/conf.py
    trunk/blender_docs/manual/glossary/index.rst
    trunk/blender_docs/manual/index.rst
    trunk/blender_docs/resources/.htaccess

Added Paths:
-----------
    trunk/blender_docs/manual/contribute/
    trunk/blender_docs/manual/contribute/build.rst
    trunk/blender_docs/manual/contribute/editing.rst
    trunk/blender_docs/manual/contribute/guides/
    trunk/blender_docs/manual/contribute/guides/maintenance_guide.rst
    trunk/blender_docs/manual/contribute/guides/markup_guide.rst
    trunk/blender_docs/manual/contribute/guides/templates.rst
    trunk/blender_docs/manual/contribute/guides/writing_guide.rst
    trunk/blender_docs/manual/contribute/index.rst
    trunk/blender_docs/manual/contribute/install/
    trunk/blender_docs/manual/contribute/install/index.rst
    trunk/blender_docs/manual/contribute/install/linux.rst
    trunk/blender_docs/manual/contribute/install/macos.rst
    trunk/blender_docs/manual/contribute/install/windows.rst
    trunk/blender_docs/manual/contribute/patch_commit.rst
    trunk/blender_docs/manual/contribute/release_cycle.rst
    trunk/blender_docs/manual/contribute/todo_list.rst
    trunk/blender_docs/manual/contribute/translations/
    trunk/blender_docs/manual/contribute/translations/add_language.rst
    trunk/blender_docs/manual/contribute/translations/contribute.rst
    trunk/blender_docs/manual/contribute/translations/style_guide.rst

Removed Paths:
-------------
    trunk/blender_docs/manual/about/

Modified: trunk/blender_docs/manual/conf.py
===================================================================
--- trunk/blender_docs/manual/conf.py	2022-07-10 01:26:21 UTC (rev 9402)
+++ trunk/blender_docs/manual/conf.py	2022-07-12 01:20:35 UTC (rev 9403)
@@ -75,7 +75,7 @@
 # that should be available in every file.
 rst_epilog = """
 .. |BLENDER_VERSION| replace:: %s
-.. |TODO| replace:: The documentation here is incomplete, you can help by :doc:`contributing </about/index>`.
+.. |TODO| replace:: The documentation here is incomplete, you can help by :doc:`contributing </contribute/index>`.
 """ % blender_version
 
 # Quit warnings about missing download file

Added: trunk/blender_docs/manual/contribute/build.rst
===================================================================
--- trunk/blender_docs/manual/contribute/build.rst	                        (rev 0)
+++ trunk/blender_docs/manual/contribute/build.rst	2022-07-12 01:20:35 UTC (rev 9403)
@@ -0,0 +1,31 @@
+.. highlight:: sh
+
+*******************
+Building the Manual
+*******************
+
+Converting the RST-files into pretty HTML pages is simple.
+
+Open a terminal or Command Prompt in the ``~/blender_docs`` directory and simply run::
+
+   make
+
+.. tip::
+
+   On Microsoft Windows you can simply open the ``make.bat`` file to easily
+   run the command without having to open the Command Prompt and typing commands.
+
+This is the command you should use when building the docs,
+however, other commands are available by typing ``make help``.
+This command will convert the RST-files into HTML pages
+and automatically open your default web browser to view the result.
+The command will continue to run and watch for changes made to the RST-files
+and refresh the HTML pages as necessary.
+
+.. note::
+
+   The converted pages can also be viewed manually by browsing the build directory: ``~/blender_docs/build/html``.
+   For example to open the home page, open ``build/html/index.html`` to read the manual.
+
+The building process may take several minutes the first time (or after any major changes),
+but for subsequent changes it should only take a few seconds.


Property changes on: trunk/blender_docs/manual/contribute/build.rst
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/blender_docs/manual/contribute/editing.rst
===================================================================
--- trunk/blender_docs/manual/contribute/editing.rst	                        (rev 0)
+++ trunk/blender_docs/manual/contribute/editing.rst	2022-07-12 01:20:35 UTC (rev 9403)
@@ -0,0 +1,88 @@
+.. highlight:: sh
+
+******************
+Editing the Manual
+******************
+
+You can modify the manual by editing local text files.
+These files are kept in sync with those online via a repository,
+based on this the server will update the online manual.
+
+The manual is written in the `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
+(RST) markup language and can be edited using a plain text editor.
+For a local preview, you convert (build) the manual source files from RST into HTML web pages.
+
+
+Update
+======
+
+Firstly, make sure that your local copy of the manual is up to date with the online repository using::
+
+   svn update
+
+
+Writing
+=======
+
+You can now edit the documentation files, which are the ``.rst``
+files inside the ``manual`` folder using a text editor of your choice.
+
+Be sure to check the :doc:`/contribute/guides/writing_guide`
+for conventions and :doc:`/contribute/guides/markup_guide`
+to learn how to write in the reStructuredText markup language.
+
+Happy writing!
+
+
+Bigger Changes
+--------------
+
+If you are going to add or overhaul a section, be sure to check carefully that it does not already exist.
+In some places, the docs are so disorganized that sections may be duplicated or in a strange location.
+In the case that you find a duplicate or out of place section,
+`create a task <https://developer.blender.org/maniphest/task/edit/form/default/?project=PHID-PROJ-c4nvvrxuczix2326vlti>`__
+explaining the issue, and optionally include a revision (actual changes).
+
+Before you make any edits that are not simple and plainly justified (for example, moving folders around),
+you should verify with a manual maintainer that your contribution is along the community's vision for the manual.
+This ensures the best use of your time and good will as it is otherwise possible that, for some reason,
+your changes will conflict and be rejected or need time-consuming review.
+For example, another person may be already working on the section you wish to change,
+the section may be scheduled for deletion or to be updated according to a planned change to Blender.
+
+:ref:`Communicating <contribute-contact>` early and frequently is the key to have a productive environment,
+to not waste people's effort and to attain a better Blender manual as a result.
+
+..
+   Communication is a very important step in community development.
+   Manual maintainers and the general community can also point to areas that are in need of big or small changes.
+
+
+Getting Help/Answers
+--------------------
+
+If you are in doubt about functionality that you wish to document,
+you should pose your questions to the Blender developers responsible for that area or ask at the unofficial user
+support channel in the ``#docs`` or ``#blender-coders`` channel in :ref:`blender-chat`.
+
+Blender itself has a system of module owners with developer and artist members who are
+responsible for the design and maintenance of the assigned Blender areas.
+See the `module owners page <https://wiki.blender.org/wiki/Process/Module_Owners/List>`__
+for more information.
+
+
+Preview
+=======
+
+To view your changes, build the manual :doc:`as instructed </contribute/build>`.
+Keep in mind that you can also build only the chapter you just edited to view it quickly.
+Open the generated ``.html`` files inside the ``build/html`` folder using your web browser,
+or refresh the page if you have it open already.
+
+
+Upload
+======
+
+When you are happy with your changes, you can upload them, so that they will be in the online manual.
+At first, this is done by submitting patches so that someone can review your changes and give you feedback.
+After, you can commit your changes directly. This process is described in detail in the next section.


Property changes on: trunk/blender_docs/manual/contribute/editing.rst
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/blender_docs/manual/contribute/guides/maintenance_guide.rst
===================================================================
--- trunk/blender_docs/manual/contribute/guides/maintenance_guide.rst	                        (rev 0)
+++ trunk/blender_docs/manual/contribute/guides/maintenance_guide.rst	2022-07-12 01:20:35 UTC (rev 9403)
@@ -0,0 +1,36 @@
+.. highlight:: sh
+
+***********
+Maintenance
+***********
+
+Adding/Removing/Moving Files
+============================
+
+When RST-files are added or removed the corresponding locale files
+are added or removed automatically by the update script.
+However, if files need to be moved please use this Python script::
+
+   python tools_rst/rst_remap.py start
+
+RST-files can then be freely moved and the remap script will move the locale file after::
+
+   python tools_rst/rst_remap.py finish
+
+It is best to avoid moving/renaming files as this breaks URLs and
+without this script translators will lose all their work in these files.
+Please ask an administrator if you think something should be renamed/moved.
+
+.. note::
+
+   This script also works for image file names.
+
+
+.. _about-contribute-guides-release:
+
+Release Checklist
+=================
+
+- Create a release branch (``blender-3.2-release/``)
+- Update the splash image: ``interface_splash_current.png`` in the release branch.
+- Increase the ``conf.py: blender_version`` variable in the trunk version.


Property changes on: trunk/blender_docs/manual/contribute/guides/maintenance_guide.rst
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/blender_docs/manual/contribute/guides/markup_guide.rst
===================================================================
--- trunk/blender_docs/manual/contribute/guides/markup_guide.rst	                        (rev 0)
+++ trunk/blender_docs/manual/contribute/guides/markup_guide.rst	2022-07-12 01:20:35 UTC (rev 9403)
@@ -0,0 +1,280 @@
+.. highlight:: rst
+
+******************
+Markup Style Guide
+******************
+
+.. Editors Note:
+   ::
+   There are many detailed conventions, e.g:
+   ::
+   - When definition lists/bullet-points are used.
+   - Word-ordering in filenames.
+   - How text is wrapped.
+   - The number of spaces between lines.
+   - When it is/is not okay to add in Unicode characters.
+   - Should comments on a page be above or below titles :)
+   ::
+   Having a lot of detailed text on this page is off-putting to new contributors,
+   so please avoid making this page into a wall-of-text,
+   many conventions can be noticed along the way by reading existing text.
+
+This page covers the conventions for writing and use of the reStructuredText (RST) markup syntax.
+
+
+Conventions
+===========
+
+- Three space indentation.
+- Lines should be less than 120 characters long.
+- Use italics for button/menu names.
+
+Other loose conventions:
+
+- Avoid Unicode characters.
+- Avoid heavily wrapped text
+  (i.e. sentences can have their own lines).
+
+
+Headings
+========
+
+.. code-block:: rst
+
+   #################
+     Document Part
+   #################
+
+   ****************
+   Document Chapter
+   ****************
+
+   Document Section
+   ================
+
+   Document Subsection
+   -------------------
+
+   Document Subsubsection
+   ^^^^^^^^^^^^^^^^^^^^^^
+
+   Document Paragraph
+   """"""""""""""""""
+
+.. note:: *Parts* should only be used for contents or index pages.
+
+.. note:: Each ``.rst`` file should only have one chapter heading (``*``) per file.
+
+
+Text Styling
+============
+
+See the `overview on ReStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__

@@ Diff output truncated at 10240 characters. @@

More information about the Bf-docboard-svn mailing list