Merge pull request #25 from mrksu/master

Fixes for newdoc

Author: Marek Suchánek

.tito/packages/python-newdoc

@@ -1 +1 @@
-1.4.0-1 newdoc/
+1.4.2-1 newdoc/

newdoc/BUILDING.adoc

@@ -62,6 +62,12 @@ This creates the new SRPM package in the `/tmp/tito/` directory on your system.
 +
 When the build finishes, the update is immediately available to users.
 
+. Delete older builds that might break the uploading step:
++
+----
+$ rm -r build dist
+----
+
 . Build the `pip` package:
 +
 ----
@@ -71,7 +77,7 @@ $ python3 setup.py sdist bdist_wheel
 . Upload the package to PyPI:
 +
 ----
-$ python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+$ python3 -m twine upload --repository-url https://upload.pypi.org/legacy/ dist/*
 ----
 
 

newdoc/CHANGELOG.adoc

@@ -1,10 +1,11 @@
 = Changelog of the `newdoc` script
 
-== WIP
+== v1.4.0, 2019-08-29
 
 New features:
 
 * newdoc is now packaged as an RPM on Copr: link:https://copr.fedorainfracloud.org/coprs/mareksu/newdoc/[].
+* Templates have been updated to match the upstream modular guidelines.
 
 == v1.3, 2018-08-22
 

newdoc/README.md

@@ -0,0 +1,126 @@
+###########################
+README: The `newdoc` script
+###########################
+
+This script is used for generating empty module and assembly files when writing Red Hat or Fedora documentation in AsciiDoc. The generated files follow template guidelines set up by the Modular Documentation initiative: https://redhat-documentation.github.io/modular-docs/.
+
+The script is now compatible with both Python 3 (for Fedora and community distributions) and Python 2.7 (for RHEL 7 and macOS).
+
+It hasn't been tested on Windows.
+
+
+============================
+How do I install the script?
+============================
+
+* To install ``newdoc`` on Fedora, use the Copr package repository: https://copr.fedorainfracloud.org/coprs/mareksu/newdoc/. See the instructions there.
+
+* On a Linux distribution that includes Python 3, use the ``pip`` package manager, version 3::
+
+ # pip3 install newdoc
+
+* On RHEL 7, CentOS 7, or macOS, use the ``pip`` package manager, version 2::
+
+ # pip install newdoc
+
+
+==========================
+How do I add a new module?
+==========================
+
+1. In the directory where modules are located, use the ``newdoc`` script to create a new file::
+
+ modules-dir]$ newdoc --procedure "Setting up thing"
+
+2. Rewrite the information in the template with your docs.
+
+The script also accepts the ``--concept`` and ``--reference`` options. You can use these short forms instead: ``-p``, ``-c``, and ``-r``.
+
+
+============================
+How do I add a new assembly?
+============================
+
+1. In the directory where assemblies are located, use the ``newdoc`` script to create a new file::
+
+ assemblies-dir]$ newdoc --assembly "Achieving thing"
+ 
+2. Rewrite the information in the template with your docs.
+
+ Add AsciiDoc include statements to include modules. See `Include Files <https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files>`_ in the AsciiDoc Syntax Quick Reference.
+
+You can use the short form of the ``--assembly`` option instead: ``newdoc -a "Achieving thing"``.
+
+
+=============
+Configuration
+=============
+
+``newdoc`` enables you to configure multiple aspects of its behavior:
+
+* Custom templates for assemblies and modules,
+* How IDs are capitalized when converted from a title,
+* What symbol is used to replace spaces in IDs.
+
+These options can be set in the ``newdoc.ini`` configuration file, which is located:
+
+* On Fedora, RHEL, and other Linux distributions, in ``~/.config/newdoc/newdoc.ini``
+* On macOS, in ``~/Library/Preferences/newdoc/newdoc.ini``
+
+The configuration file is not created automatically: if you want to set custom options, create it using a plain text editor.
+
+The file must always start with the ``[newdoc]`` header. An example configuration is available in this repo at ``examples/newdoc.ini``.
+
+
+----------------
+Custom templates
+----------------
+
+In the config file, you can set paths to custom AsciiDoc template files for each module type. The options are:
+
+* ``assembly_template``
+* ``concept_template``
+* ``procedure_template``
+* ``reference_template``
+
+For example, to use a custom template for reference modules, use::
+
+ reference_template = ~/.config/newdoc/my-reference-template.adoc
+
+``newdoc`` performs substitutions on the templates using the Python ``string.template`` library. The following strings are replaced:
+
+* ``${module_title}`` with the entered title of the module
+* ``${module_id}`` with the generated ID of the module
+* ``${filename}`` with the generated file name of the module
+
+For more details on the template syntax, see: https://docs.python.org/3/library/string.html#template-strings
+
+
+----------------
+ID substitutions
+----------------
+
+* The ``id_case`` option in the config file controls how the letter case should change from the title to the ID:
+
+ * ``id_case = lowercase``: All letters in the ID will be lower-case
+ * ``id_case = capitalize``: The first letter will be upper-case, the rest lower-case
+ * ``id_case = preserve``: Keep the capitalization as entered in the title
+
+* The ``word_separator`` option lets you choose the symbol (or string) used to replace spaces in the ID. The default is a dash::
+
+ word_separator = -
+
+=====
+Notes
+=====
+
+* If you prefer ``newdoc`` to generate file without the explanatory comments, add the ``--no-comments`` or ``-C`` option when creating documents.
+
+
+====================
+Additional resources
+====================
+
+* `Modular Documentation Reference Guide <https://redhat-documentation.github.io/modular-docs/>`_
+* `AsciiDoc Mark-up Quick Reference for Red Hat Documentation <https://redhat-documentation.github.io/asciidoc-markup-conventions/>`_
+

newdoc/README.rst

@@ -1,7 +1,7 @@
 %global srcname newdoc
 
 Name: python-%{srcname}
-Version: 1.4.0
+Version: 1.4.2
 Release: 1%{?dist}
 Summary: A script to generate assembly and module AsciiDoc files from templates
 
@@ -64,6 +64,14 @@ A script to generate assembly and module AsciiDoc files from templates
 %{_bindir}/newdoc
 
 %changelog
+* Mon Sep 30 2019 Marek Suchánek <msuchane@redhat.com> 1.4.2-1
+- Fix: Remove a redundant, outdated statement to restore assembly context
+ (msuchane@redhat.com)
+
+* Sat Aug 31 2019 Marek Suchánek <msuchane@redhat.com> 1.4.1-1
+- Converted the readme to RST because PyPI literally can't handle anything else
+ (msuchane@redhat.com)
+
 * Thu Aug 29 2019 Marek Suchánek <msuchane@redhat.com> 1.4.0-1
 - Updated the templates to match upstream; Issue#18
  (msuchane@redhat.com)

newdoc/newdoc.spec

@@ -42,10 +42,6 @@ This paragraph is the assembly introduction. It explains what the user will acco
 * For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 
-// The following line is necessary to allow assemblies be included in other
-// assemblies. It restores the `context` variable to its previous state.
-:context: {parent-context-of-${module_id}}
-
 // Restore the context to what it was before this assembly.
 ifdef::parent-context-of-${module_id}[:context: {parent-context-of-${module_id}}]
 ifndef::parent-context-of-${module_id}[:!context:]

newdoc/newdoc/templates/assembly_title.adoc

@@ -1,18 +1,18 @@
 # coding=utf-8
 import setuptools
 
-with open("README.md", "r") as fh:
+with open("README.rst", "r") as fh:
  long_description = fh.read()
 
 setuptools.setup(
  name="newdoc",
- version="1.4.0",
+ version="1.4.2",
  license="GPLv3+",
  author="Marek Suchánek",
  author_email="marek.suchanek@protonmail.com",
  description="A script to generate assembly and module AsciiDoc files from templates.",
  long_description=long_description,
- long_description_content_type="text/markdown",
+ # long_description_content_type="text/markdown",
  url="https://github.com/mrksu/tools/tree/master/newdoc",
  packages=setuptools.find_packages(),
  entry_points={